refine

name	refine
description	Refine and plan a GitHub issue for implementation. Reads the issue, explores the codebase, creates a UX mockup if needed, writes a step-by-step implementation plan, and updates the issue body.

Refine Issue for Implementation

You are refining a GitHub issue into an actionable implementation plan. The argument is the issue number (e.g., /refine 336).

Step 1: Read the Issue

gh issue view <number>

Read the full issue body. Extract:

• Goal: What needs to be built or changed
• Acceptance criteria: What "done" looks like
• Design decision: Any chosen mockup option or UX direction
• Dependencies: Other issues this depends on

Step 2: Assess Clarity — Ask Clarifying Questions if Needed

Before exploring code, evaluate whether the issue is clear enough to plan:

Ask clarifying questions if:

• The issue has no acceptance criteria
• The scope is ambiguous ("improve the UI", "make it faster")
• There are multiple valid approaches and no design decision
• The issue references concepts not defined elsewhere

Proceed without asking if:

• The issue has clear acceptance criteria
• A design/mockup has already been chosen
• The scope and approach are unambiguous

Use AskUserQuestion to gather answers before continuing. Frame questions with specific options when possible.

Step 3: Check for Existing Mockup

Look for a mockup that matches the issue:

ls mockups/ 2>/dev/null | grep -i <feature-keyword>

If a mockup exists AND has a chosen design: Read the mockup file, note the chosen option, and incorporate it into the plan.

If a mockup exists but NO design is chosen: Read it, then ask the user which option they prefer before proceeding.

If NO mockup exists AND the issue involves UI changes: Create one (see Step 4).

If NO mockup exists AND the issue is backend-only: Skip to Step 5.

Step 4: Create UX Mockup (When Needed)

Create the mockups/ directory if it doesn't exist (mkdir -p mockups), then create a standalone HTML mockup file at mockups/<feature-name>.html with 10 distinct design options.

Mockup Template

Follow the exact pattern used in existing mockups if any exist. Key requirements:

1. Use the project's design system — include Tailwind CDN, PrimeIcons, and any project-specific CSS variables for theming (light/dark mode).

2. Include these standard elements:

   • Tailwind CDN (https://cdn.tailwindcss.com)
   • PrimeIcons (https://unpkg.com/primeicons@7.0.0/primeicons.css)
   • Theme toggle button (fixed top-right)
   • toggleTheme() script

3. For each option include:

   • Numbered option card with title and subtitle
   • Visual mockup of the design in context
   • Pros/cons list (green for pros, red for cons)
   • Option dividers between each option

4. Mark one option as "Recommended" with:

   • Green border highlight
   • "Recommended" badge in the header
   • Clear reasoning for why it's recommended

5. Include a comparison table at the bottom summarizing all options across key dimensions.

6. Include a "Recommendation" section explaining the recommended choice.

Third-Party UI Extensions

When the plan involves integrating a UI library or extension, identify the actual DOM output by reading the library's source code or documentation. Do NOT assume standard HTML elements — many libraries (TipTap, ProseMirror, Slate, etc.) use custom NodeViews that render non-standard DOM structures. Include the actual DOM structure in the plan so CSS selectors, query selectors, and interaction logic are correct from the start.

After creating the mockup, open it for the user:

# macOS:
open mockups/<feature-name>.html
# Linux:
xdg-open mockups/<feature-name>.html

Then tell the user: "I've created a mockup with 10 design options and recommended Option X. Please review and let me know which option you prefer, or I'll proceed with the recommended one."

Wait for the user's response before continuing.

Step 5: Explore the Codebase

Thoroughly explore all code relevant to the issue. Be exhaustive — missing a file here means a broken plan.

What to Find

Backend (always check all of these):

• Relevant domain entities/aggregates (look in src/FlatRate.Domain/Aggregates/)
• Repository interfaces in Domain layer
• Repository implementations in Infrastructure layer (src/FlatRate.Infrastructure/Persistence/Repositories/)
• Application layer handlers/queries/commands (src/FlatRate.Application/)
• DTOs and response models
• API endpoints (src/FlatRate.Web/Endpoints/)
• Existing patterns to follow (e.g., how similar features were built)

Frontend (always check all of these):

• Models/interfaces (*.model.ts)
• Services (*.service.ts)
• Page components (*.page.ts)
• Shared components (*.component.ts)
• Template markup (inline templates in component files)

Cross-cutting (always check):

• Callers of methods being changed (use grep to find all call sites)
• Optimistic update patterns (look for increment/decrement/update calls on services)
• Existing tests for the area being modified (check tests/ directory)
• Related mockups or design decisions

Exploration Techniques

# Find relevant files by keyword
grep -r "MethodName" src/ --include="*.cs" --include="*.ts" -l

# Find all callers of a method
grep -r "methodName" src/ --include="*.ts" -l

# Check for existing tests
grep -r "ClassName" tests/ --include="*.cs" -l

# Understand the domain model
cat src/FlatRate.Domain/Aggregates/<Entity>/<Entity>.cs

Read the full contents of every relevant file. Don't just find file names — read the actual code to understand:

• Method signatures and return types
• How data flows from API → handler → repository → database
• What patterns exist that should be followed
• What optimistic update hooks exist on the frontend

Step 6: Write the Implementation Plan

Write a concrete, step-by-step implementation plan with:

Plan Structure

Each step must include:

1. Step title — what's being done
2. Files table — exact file paths and what changes in each
3. Code snippets — show the actual code to write (not pseudocode), referencing existing patterns

Plan Rules

• Order steps by dependency — backend before frontend, interfaces before implementations
• One concern per step — don't mix repository changes with UI changes
• Show the pattern to follow — if there's existing code that does something similar, reference it explicitly (e.g., "Follow the same pattern as BillRepository.GetByPropertyIdAsync at line 28-42")
• Include optimistic update changes — if the change affects data that's optimistically updated on the frontend, include steps to update all callers
• Include test expectations — note what tests should be added or updated (but don't write the test code in the plan)

Plan Quality Requirements (ENFORCED)

These requirements ensure sub-agents can implement the plan without ambiguity or missed updates.

1. Exact Method Signatures

For any method being created or modified, the plan must include the full method signature — not just the file path. This prevents sub-agents from guessing parameter types, return types, or method names.

**Method signature:**
\`\`\`csharp
// New method in IBillRepository
Task<IReadOnlyList<Bill>> GetByPropertyIdAsync(Guid propertyId, CancellationToken ct = default);
\`\`\`

\`\`\`typescript
// New method in bill.service.ts
loadByPropertyId(propertyId: string): void
\`\`\`

Do NOT write vague instructions like "add a method to get bills by property" — show the exact signature.

2. List All Callers

For any method being changed (signature, behavior, or return type), the plan must identify all call sites by running grep and listing the results. Sub-agents must not discover missing callers mid-implementation.

**Callers of `BillRepository.GetByPropertyIdAsync` (must be updated):**
- `src/FlatRate.Application/Features/Bills/GetBillsByProperty.cs:34`
- `src/FlatRate.Web/ClientApp/src/app/bills/bill.service.ts:42`

If a method has zero callers (new method), state that explicitly: "No existing callers — this is a new method."

3. Template HTML Before/After

For UI changes, show the exact HTML being modified with before and after snippets. Do not write "update the template to show the new field" — show the actual markup.

**Before** (from `bills.page.ts` template, lines 45-52):
\`\`\`html
<div class="flex items-center gap-2">
  <span class="text-sm text-foreground">{{ bill.amount }}</span>
</div>
\`\`\`

**After:**
\`\`\`html
<div class="flex items-center gap-2">
  <span class="text-sm text-foreground">{{ bill.amount }}</span>
  @if (bill.isPaid) {
    <span class="text-xs text-success">Paid</span>
  }
</div>
\`\`\`

4. List Shared Components to Reuse

Explicitly name shared components (with file paths) that the implementation should use, and warn against creating duplicates. Check src/app/shared/components/ and src/app/shared/services/ before planning any new shared utility.

**Shared components to reuse:**
- `src/app/shared/components/error-state.component.ts` — use for API error display
- `src/app/shared/components/delete-confirm-button.component.ts` — use for inline delete
- `src/app/shared/services/toast.service.ts` — use for mutation success/error feedback

**Do NOT create:** A new error display component, toast wrapper, or confirmation dialog — these already exist.

5. Pre-Flight Completeness Checklist

Append this machine-readable checklist to the end of every refined issue body. Every box must be checked before the issue is considered fully refined.

## Pre-Flight Checklist

- [ ] All callers of modified methods identified
- [ ] Shared components listed (or confirmed none apply)
- [ ] Template HTML before/after included (for UI changes)
- [ ] Method signatures specified for new/modified methods
- [ ] Verification steps defined for each acceptance criterion
- [ ] Optimistic update impact assessed
- [ ] E2E test decision documented (add/skip with reason)

If a checklist item does not apply (e.g., "Template HTML" for a backend-only change), check it and add "N/A — backend only".

6. Verification Contracts

Each acceptance criterion must have a concrete verification contract describing exactly what to navigate to, interact with, and assert during browser validation. This replaces vague criteria like "the feature works" with testable steps.

## Acceptance Criteria

- [ ] Bills can be filtered by property
  - **Verify:** Navigate to `/bills`. Click the property filter. Select "123 Main St". Assert that only bills for that property are visible. Clear the filter. Assert all bills reappear.

- [ ] Paid badge shows correct color
  - **Verify:** Create a bill and mark it as paid. Navigate to `/bills`. Assert the paid badge has class `text-success`.

Plan Template

## Implementation Plan

### Step 1 — [Area]: [What]

**Files:**

| File | Change |
|------|--------|
| `path/to/file.cs` | Description of change |

**Method signatures** (new/modified):
\`\`\`csharp
Task<Result> NewMethodAsync(Guid userId, string title, CancellationToken ct = default);
\`\`\`

**Callers** (for modified methods):
- `path/to/caller1.cs:34` — update to pass new parameter
- `path/to/caller2.ts:58` — update return type handling

**Shared components to reuse:**
- `src/app/shared/components/error-state.component.ts` — for error display

**Pattern to follow** (from `path/to/existing.cs:28-42`):
\`\`\`csharp
// Existing code that shows the pattern
\`\`\`

**Template before/after** (for UI steps):
\`\`\`html
<!-- Before (line 45-52) -->
<div>...</div>

<!-- After -->
<div>...updated...</div>
\`\`\`

**New code:**
\`\`\`csharp
// The actual code to write
\`\`\`

### Step 2 — ...

Step 7: Propose E2E Tests

After completing the implementation plan, assess whether the feature warrants E2E test coverage.

Evaluation Criteria

Propose a test if the feature involves:

• Third-party library integration (custom DOM, NodeViews, plugins)
• New DOM structures not covered by existing tests
• Multi-step interaction flows (insert → interact → verify)
• Data persistence through complex UI paths

Do NOT propose tests for:

• Simple styling changes
• Individual formatting buttons (bold, italic) — tested upstream by the library
• Tooltip additions, icon changes
• Features fully covered by existing unit tests

If no tests meet the evaluation criteria, skip this step entirely — don't ask about tests that aren't worth writing.

Presentation Flow — One Test at a Time

For each candidate E2E test, use AskUserQuestion to present it individually:

Question: "Should we add this E2E test?"
Header: "E2E Test"
Options:
  - "Yes" — Include this test in the implementation plan
  - "No" — Skip this test
  - (User can also select "Other" to describe modifications)

Description for the question should include:
  - Test name (e.g., "can filter bills by property")
  - Test file (e.g., tests/FlatRate.E2E.Tests/tests/bills.spec.ts)
  - What it exercises (e.g., "Filter bills by property → verify filtered results → clear filter → verify all bills return")
  - Why it's valuable (e.g., "Core billing workflow — would catch filter logic bugs")

Present tests one at a time, waiting for the user's response before presenting the next. This ensures each test gets individual consideration rather than being rubber-stamped as a batch.

After All Tests Are Reviewed

• Add approved tests as implementation steps in the plan
• Note which tests were declined (for traceability)
• If the user modified a test, incorporate their feedback into the plan

Step 8: Update Labels

After writing the plan, update the issue labels:

• Remove the to-refine label
• Add the refined label
• Add any relevant feature labels

gh issue edit <number> --remove-label "to-refine" --add-label "refined"

Step 9: Update the GitHub Issue Body

Replace the issue body with the refined version. Preserve the original sections (Overview, Dependencies, Chosen Design) and add/overwrite the Implementation Plan section.

Use gh issue edit with a heredoc:

gh issue edit <number> --body "$(cat <<'ISSUE_BODY'
## Overview
[preserved from original]

## Dependencies
[preserved from original]

## Chosen Design
[preserved or updated based on mockup selection]

---

## Implementation Plan

### Step 1 — ...
[the full plan]

---

## Acceptance Criteria
[preserved or refined from original — each criterion includes a verification contract]

---

## Pre-Flight Checklist

- [ ] All callers of modified methods identified
- [ ] Shared components listed (or confirmed none apply)
- [ ] Template HTML before/after included (for UI changes)
- [ ] Method signatures specified for new/modified methods
- [ ] Verification steps defined for each acceptance criterion
- [ ] Optimistic update impact assessed
- [ ] E2E test decision documented (add/skip with reason)
ISSUE_BODY
)"

What to Include in the Updated Issue

• Overview — keep the original, or refine for clarity
• Dependencies — preserve as-is
• Chosen Design — update if a mockup was created/selected in this session
• Implementation Plan — the full step-by-step plan from Step 6
• Acceptance Criteria — preserve original, add any new criteria discovered during planning. Each criterion must have a verification contract (see Plan Quality Requirements, item 6)
• Pre-Flight Checklist — the completeness checklist from Plan Quality Requirements, item 5

What NOT to Include

• Internal exploration notes or reasoning
• Alternative approaches that were rejected
• Code that was read but not relevant to the plan

Step 10: Summary

Tell the user:

1. What you found during exploration
2. How many steps the plan has
3. Any risks or decisions that need attention
4. Link to the updated issue