resolve-code-review

name	resolve-code-review
description	Walk through code review findings one at a time and decide a resolution for each — fix, skip, dismiss, or defer. Use "auto" for autonomous resolution with TDD.
argument-hint	[auto] [high|medium|all] [file]

Resolve Code Review Findings

Iterate through code review findings, presenting each issue and resolving it. Every finding ends with a resolution: fixed, skipped, dismissed, or deferred.

Two modes:

• Interactive (default): Present one finding at a time, wait for user input.
• Auto (auto argument): Ask clarifying questions upfront, then autonomously resolve each finding using best judgment. Prefers TDD when test infrastructure is available.

Critical Behavior Requirements

YOU MUST FOLLOW THESE RULES:

Interactive Mode (default)

1. MANDATORY STOP: You MUST use AskUserQuestion to present each finding and wait for the user's choice BEFORE taking ANY action. Do NOT implement fixes autonomously.

2. ONE AT A TIME: Process findings ONE AT A TIME. Never batch multiple findings together. Never present more than one finding per response.

3. NO AUTONOMOUS FIXES: Never implement a fix without explicit user approval via AskUserQuestion response.

Auto Mode

1. UPFRONT QUESTIONS ONLY: Ask ALL clarifying questions together in a single interaction BEFORE beginning the fix loop. After the user confirms, do NOT stop to ask — proceed autonomously through every finding.

2. BEST-EFFORT DECISIONS: For each finding, decide whether and how to fix it based on the Auto Mode Decision Criteria. Apply fixes or skip findings without waiting for user input.

3. VERIFY BEFORE FIXING: Findings are inputs to evaluate, not orders. Before fixing anything, verify the finding against the current code (see Verify-First Rule).

4. PREFER TDD: When the project has test infrastructure (test framework configured, existing test files), use the TDD workflow (Red → Green → Refactor) for TDD-eligible findings. Fall back to direct fix when TDD is not feasible.

5. PROGRESS REPORTING: Show a brief one-line status after each finding is processed. Do NOT present full finding details — just the finding number, title, and resolution.

6. STOP ON FAILURE: If a fix fails to compile or breaks existing tests, revert the change, record the finding as skipped (with reason), and continue to the next finding. Do NOT stop to ask the user.

Both Modes

• STATE TRACKING: After presenting the summary, write progress state to .decaf/code-reviews/.resolve-state.json. Update this file after each finding is processed. This enables recovery after context compaction.

Verify-First Rule

Applies to every fix action, in both modes. A finding is a claim, not a fact — the code may have changed since the review, and reviewers (and even the validation wave) can be wrong.

Before implementing any fix:

1. Re-verify the finding against the current code: does the claimed issue actually exist, here, now?
2. If the finding is not real (refuted by the code, already fixed, mis-cited): resolve it as Not addressing — record it under dismissed with the concrete evidence. Do not apply a fix to satisfy the finding.
3. If the finding is real but the suggested fix would cause harm (breaks behavior, conflicts with a documented decision, worsens the code): resolve it as Declined, citing the specific harm — record it under skipped with that reason. In interactive mode, present the concern to the user instead of silently declining.
4. If the finding is real but the suggested fix is wrong, fix it correctly and record fixed (differently) with a one-line note on why the approach differs.

Findings the review marked unvalidated or validation failed (kept) get extra skepticism — the validation wave could not confirm them.

No performative agreement: never "fix" something just because a reviewer said so; the evidence decides.

Argument Parsing

Parse $ARGUMENTS to determine mode, severity filter, and code review file:

Mode (positional, optional):

• auto — autonomous mode: ask questions upfront, then resolve without stopping
• (omitted) — interactive mode (default)

Severity filter (positional, optional):

• high — only Critical + High findings
• medium — Critical + High + Medium findings
• all (default) — all findings

File (remaining argument, optional):

• If a file path is provided: Use that specific file
• Otherwise: Use the most recent .decaf/code-reviews/CODE_REVIEW_*.md file

Examples: auto, auto high, high, auto medium myreview.md, all myreview.md

Execution Steps

Step 1: Locate the Code Review File

If $ARGUMENTS specifies a file:

• Verify the file exists
• If not found, inform the user and exit

Otherwise, find the latest review:

ls .decaf/code-reviews/CODE_REVIEW_*.md 2>/dev/null | sort -r | head -1

If no code review file exists, inform the user:

No code review found. Run /decaf-quality:code-review first to generate one.

Step 2: Parse Findings

Read the code review file and extract the primary findings. Findings are identified by headers matching the pattern:

### #N 🔴|🟠|🟡|🟢 Severity: Title

Build a list of findings with:

• Number (#1, #2, etc.)
• Severity (Critical, High, Medium, Low)
• Title
• File and line
• Confidence anchor (100, 75, or 50) and any unvalidated / validation failed marker
• Whether the validation wave confirmed it
• Issue description
• Suggested fix (note if multiple options are presented)

Other report sections are not part of the main queue:

• Pre-existing Issues (### P1 ... headers): excluded by default. If any Critical/High pre-existing issues exist, note their count in the summary — Step 6.5 offers to walk them afterwards.
• Minor Findings — Consistency: walked through with the main queue — these are verified, change-introduced, and usually a one-line fix. Parse the Consistency one-liners (file:line — title (agent)) into the queue alongside the ### #N primaries; the severity filter below still applies (they are Low/Medium).
• Minor Findings — Testing Gaps / Residual Risks: not walked — listed once in the session summary as awareness items.

Filter by severity: Apply the severity filter from arguments. Remove findings below the threshold:

• high: Keep only Critical and High
• medium: Keep Critical, High, and Medium
• all: Keep everything

Identify similar issues: Group findings that share the same underlying pattern (e.g., "missing null check", "missing empty collection guard", "undocumented parameter"). Track these groups to enable batch fixing.

Step 2b: Detect Test Infrastructure (Auto Mode Only)

When in auto mode, detect whether the project has test infrastructure:

1. Search for test files: Look for files matching *.test.*, *.spec.*, *_test.*, *Tests.*, or directories named tests, __tests__, test
2. Search for test framework config: Look for jest.config.*, pytest.ini, pyproject.toml (with pytest section), *.csproj (with test SDK), go.mod (with testing), Cargo.toml (with dev-dependencies), etc.
3. Identify test command: Determine how to run tests (e.g., dotnet test, go test ./..., npm test, pytest, cargo test)

Record in state:

{
  "testInfra": {
    "available": true,
    "framework": "xunit|jest|pytest|go-test|...",
    "testCommand": "dotnet test|npm test|..."
  }
}

Step 3: Check for Existing State

Check if .decaf/code-reviews/.resolve-state.json exists:

• If yes and it references the same review file, offer to resume from where we left off
• If no or different file, start fresh

Step 4: Present Summary and Initialize State

Interactive Mode

Show the user the overall summary:

## Code Review: [filename]

| Severity | Count |
|----------|-------|
| 🔴 Critical | X |
| 🟠 High | X |
| 🟡 Medium | X |
| 🟢 Low | X |

**Total findings:** N [ | **Pre-existing Critical/High:** M (offered at the end)]

I'll walk you through each finding ONE AT A TIME. For each one, choose a resolution:
- **Apply Fix**, Fix (TDD), Fix All Similar
- **Skip**, Dismiss (false positive), Defer (create work item)

Auto Mode

Show the summary AND the planned resolution for every finding, then ask for confirmation.

4a. Build the action plan. For each finding, apply the Auto Mode Decision Criteria to determine the planned action: Fix (TDD), Fix, Fix All Similar, Defer, or Skip.

4b. Present the plan:

## Code Review: [filename] — Auto Mode

| Severity | Count |
|----------|-------|
| 🔴 Critical | X |
| 🟠 High | X |
| 🟡 Medium | X |
| 🟢 Low | X |

**Total findings:** N | **Test infrastructure:** [Yes (framework) | No]

### Planned Resolutions

| # | Severity | Title | File | Planned Action | Reason |
|---|----------|-------|------|----------------|--------|
| 1 | 🔴 Critical | Null ref in handler | Foo.cs:42 | Fix (TDD) | Behavioral bug, tests available |
| 2 | 🟠 High | SQL injection | Bar.cs:17 | Fix | Security, no test seam |
| 3 | 🟡 Medium | Extract shared logic | Baz.cs:99 | Defer | Requires design decision on abstraction |
| 4 | 🟡 Medium | Rename method | Qux.cs:12 | Skip | Naming/cosmetic |
| ... | ... | ... | ... | ... | ... |

### Questions

[List any findings that need user input — e.g., findings with multiple fix options where the agent can't confidently choose, or Critical findings at anchor 50. For each, state the finding number, the options, and what the agent recommends.]

If no questions: "No ambiguous findings — ready to proceed."

4c. Ask for confirmation:

AskUserQuestion with:
- question: "Review the plan above. Should I proceed, or do you want to adjust any items? (You can say things like '#3 fix instead of skip' or 'skip all Low')"
- header: "Auto Mode Plan"

⚠️ STOP HERE AND WAIT FOR USER RESPONSE.

4d. Process user response:

• If the user says "go", "proceed", "yes", "looks good", etc.: begin the fix loop
• If the user adjusts items: update the plan accordingly, re-display the changed rows, and ask again
• If the user answers the listed questions: record their choices for use during the fix loop

Both Modes — Initialize State

Write initial state to .decaf/code-reviews/.resolve-state.json:

{
  "mode": "interactive|auto",
  "reviewFile": ".decaf/code-reviews/CODE_REVIEW_xxx.md",
  "totalFindings": 12,
  "currentIndex": 0,
  "processed": [],
  "actions": { "fixed": 0, "fixedTdd": 0, "fixedBatch": 0, "skipped": 0, "dismissed": 0, "deferred": 0 },
  "similarGroups": { "pattern-name": [1, 3, 7] },
  "deferSystem": null,
  "testInfra": { "available": false },
  "plannedActions": { "1": "fixTdd", "2": "fix", "3": "defer", "4": "skip" }
}

Step 5: Process Findings

Interactive Mode — Process Each Finding (MANDATORY STOP POINT)

For each finding, starting with the highest severity:

5a. Present the finding:

## Finding #N of M: [Severity Icon] [Title]

**File:** `path/to/file.cs:line`
**Category:** category
**Found by:** agent1, agent2
**Confidence:** [100 | 75 | 50] [ (unvalidated)]

### Issue
[Issue description]

### Suggested Fix
[Fix description and code snippet if applicable]

5b. MANDATORY: Present options and wait for user choice.

Build the full list of fix and skip options first, then decide how to present them.

Available fix options (built dynamically):

Option	Condition	Description
"Apply Fix"	Always present	Implement the suggested fix
"Apply Fix (TDD)"	Testable behavioral bug AND not a test file	Write failing test first, then fix
"Fix All Similar"	Other unprocessed findings share same pattern	Fix this and N other similar issues
"Fix All Similar (TDD)"	Both TDD and batch conditions met	TDD workflow for all similar issues

TDD eligibility:

• NOT a test file (filename contains test, spec, or is in tests/__tests__ directory)
• Testable code (NOT documentation, comments, naming, formatting, or config changes)
• Behavioral bug that can be verified with a test

If the suggested fix has multiple distinct options (e.g., "Option 1: ... or Option 2: ..."), replace the single "Apply Fix" option with "Apply Fix (Option 1)", "Apply Fix (Option 2)", etc.

Available skip options (always 3):

Option	Description
"Skip"	Move to next finding, no tracking
"Dismiss"	Mark as false positive
"Defer"	Create a work item for later

Presentation rule — flatten when possible:

AskUserQuestion supports max 4 options. Count the total options (fix options + skip options). If the total is <= 4, present them all in a single AskUserQuestion:

AskUserQuestion with:
- question: "How would you like to resolve this finding?"
- header: "Resolution"
- options: [all fix options + all skip options, max 4]

If the total is > 4, use a two-step flow:

Step 1 — top-level choice:

AskUserQuestion with:
- question: "How would you like to resolve this finding?"
- header: "Resolution"
- options:
  - label: "Fix...", description: "Address this finding (more options)"
  - label: "Skip...", description: "Don't fix this now (more options)"

⚠️ STOP HERE AND WAIT FOR USER RESPONSE.

Step 2 — follow-up based on choice:

If user chose "Fix...":

AskUserQuestion with:
- question: "Which fix approach?"
- header: "Fix type"
- options: [dynamically built fix options list]

If user chose "Skip...":

AskUserQuestion with:
- question: "How should this finding be tracked?"
- header: "Skip type"
- options:
  - label: "Skip", description: "Move to next finding, no tracking"
  - label: "Dismiss", description: "Mark as false positive"
  - label: "Defer", description: "Create a work item for later"

⚠️ STOP HERE AND WAIT FOR USER RESPONSE.

5c. Handle the final response (both modes use these action implementations):

→ Jump to Action Implementations.

5d. Update state file after each action:

{
  "currentIndex": 4,
  "processed": [{ "finding": 4, "action": "fixed|fixedTdd|fixedBatch|skipped|dismissed|deferred|other" }],
  "actions": { "fixed": 1, "fixedTdd": 1, "fixedBatch": 0, "skipped": 1, "dismissed": 1, "deferred": 0 }
}

For dismissed findings, include reason: { "finding": 4, "action": "dismissed", "reason": "..." } For deferred findings, include work item reference: { "finding": 4, "action": "deferred", "workItem": "..." } For batch fixes, add entries for all affected findings to the processed array.

5e. Show progress:

✅ Finding #N resolved. (X of M remaining)

5f. Return to 5a for next finding. Do NOT batch - present one finding, wait, process, repeat.

Auto Mode — Autonomous Resolution Loop

After the user confirms the plan in Step 4, iterate through all findings automatically:

For each finding, starting with the highest severity:

1. Read the planned action from the confirmed plan (or user-overridden action)
2. Execute the action using the Action Implementations — the Verify-First Rule applies to every fix action. For Defer actions: detect or reuse deferSystem, create a follow-up work item with finding details, severity, and deferral reason.
3. Verify (fix actions only): Run testCommand (if available) or verify compilation after each fix. If verification fails:
   • Revert the change
   • Record as skipped with reason: "fix failed: [error summary]"
   • Continue to next finding
4. Report progress (one line):

   ✅ #N [Title] — fixed | ✅ #N [Title] — fixed (differently): [why] | 🚫 #N [Title] — not addressing: [evidence] | ⛔ #N [Title] — declined: [harm] | 📋 #N [Title] — deferred: [work item ref] | ❌ #N [Title] — skipped: [reason]
   

5. Update state file (same format as interactive mode)
6. Process similar findings together: When reaching a finding that belongs to a similar group and the planned action is "Fix All Similar", process all findings in the group at once, then skip them individually as they come up.
7. Continue to next finding. Do NOT stop.

Action Implementations

These implementations are shared by both modes. Every fix action starts with the Verify-First Rule.

• Apply Fix (or Apply Fix (Option N)): Verify the finding, implement the suggested fix (or specified option), verify it compiles, show the result
• Apply Fix (TDD) / Fix All Similar (TDD): Verify the finding, then follow the TDD workflow:
  1. Red: Write test(s) that expose the bug/issue. Run tests and verify they fail for the expected reason.
  2. Green: Implement the fix. Run tests and verify they now pass.
  3. Refactor (optional): Clean up if needed while keeping tests green.
  4. Show the user the test(s) created and the fix applied.
• Fix All Similar: Apply the same fix pattern to all similar issues:
  1. List all affected files/locations
  2. Verify and apply the fix at each location (verify-first applies per location — a pattern real in one file may be guarded in another)
  3. Verify compilation
  4. Mark all related findings as processed
• Skip: Record as skipped, proceed to next
• Dismiss: Record as dismissed. In interactive mode, the user may provide a reason via the free-form "Other" option — if so, store it. Otherwise record reason as "dismissed". In auto mode, include the dismissal reason from the decision criteria or the verify-first evidence (not addressing).
• Defer: Create a work item in the project's tracking system:
  1. Detect tracking system: Check project CLAUDE.md for references to tracking systems (Azure DevOps, GitHub Issues, Nibs, TODO comments, etc.)
  2. First defer: If no system detected and deferSystem is null in state file, ask the user which system to use via AskUserQuestion. Store the choice in state file under "deferSystem".
  3. Subsequent defers: Reuse deferSystem from state file.
  4. Create work item: Create the item in the appropriate system (e.g., ADO task, GitHub issue, TODO comment in code). Store the work item reference.
• Other (free-form, interactive mode only): Implement whatever the user describes. If user types "Stop", jump to Step 6.

Step 6: Session Summary

When all findings are processed or the user stops:

## Resolution Session Complete

| Resolution | Count |
|--------|-------|
| Fixed | X |
| Fixed (TDD) | X |
| Fixed (Batch) | X |
| Skipped | X |
| Dismissed | X |
| Deferred | X |

### Changes Made
- [List of files modified and what was done]

### Remaining Issues
- [List of skipped or unprocessed findings, if any]
- [Deferred items with their work item references]

### Dismissed Findings
- [List of false positives with reasons — including verify-first "not addressing" outcomes with their evidence]

### Awareness Items (not walked through)
- [Minor Findings (Consistency / Testing Gaps / Residual Risks) from the report, verbatim, if any]

### Agent Summary
[Copy the Agent Summary table from the code review file verbatim]

Delete .decaf/code-reviews/.resolve-state.json when complete.

Step 6.5: Offer Pre-existing Issues (Interactive Mode Only)

If the report's Pre-existing Issues section contains Critical or High entries that were not walked through:

AskUserQuestion with:
- question: "The review also found N pre-existing Critical/High issues in code this change didn't touch. Walk through those too?"
- header: "Pre-existing"
- options:
  - label: "Yes", description: "Resolve the pre-existing Critical/High issues the same way"
  - label: "No", description: "Leave them — they don't block this change"

If yes, run them through Step 5 the same way (they are tracked in the same state file with a P prefix).

Step 7: Clean Up Review File

Ask whether to delete the code review file that was just processed:

AskUserQuestion with:
- question: "Delete the code review file ([filename])?"
- header: "Clean up"
- options:
  - label: "Yes", description: "Delete the review file"
  - label: "No", description: "Keep the review file"

If the user chooses "Yes", delete the code review file.

Step 8: Re-review Suggestion

If any fixes were applied during the session:

1. List the files that were modified
2. Ask via AskUserQuestion:

AskUserQuestion with:
- question: "Run a quick code review on the modified files to verify fixes?"
- header: "Re-review"
- options:
  - label: "Yes", description: "Run /decaf-quality:code-review low on modified files"
  - label: "No", description: "Done for now"

If the user chooses "Yes", invoke /decaf-quality:code-review low <modified-files>.

Auto Mode Decision Criteria

Use these rules to decide the planned resolution for each finding in auto mode. Primary findings arrive post-gate, so their anchors are 100, 75, or — for Critical only — 50.

Fix (TDD) — preferred when all conditions met:

• Test infrastructure is available
• Finding is TDD-eligible (behavioral bug, not a test file, not cosmetic)
• Anchor is 75 or 100, and the finding is not marked unvalidated

Fix (direct) — when TDD not feasible:

• Severity is Critical or High at anchor 75+ (always attempt)
• Severity is Medium at anchor 100, or anchor 75 with a clear single fix
• Security findings at anchor 75+ (always attempt)

Fix All Similar — when pattern group exists:

• Multiple findings share the same pattern
• The fix for one applies uniformly to all
• Apply TDD variant if test infrastructure available and eligible

Defer — when the finding is valid but can't be fixed in this pass:

• Critical at anchor 50 — serious if real, but not verifiable enough for an autonomous fix; a human decides (in iteration-1 questions, offer it to the user instead)
• Fix would require significant design decisions beyond the finding's scope
• Finding is too broad or requires larger architectural changes
• Fix has multiple conflicting options AND user did not resolve in upfront questions
• Finding spans multiple subsystems or requires cross-cutting coordination

Create a follow-up work item in the project's issue tracker (using the same deferSystem logic as interactive mode). Include the finding details, severity, and why it was deferred.

Skip — when fix is not appropriate:

• Severity is Low (unless trivially fixable like removing unused imports)
• Purely cosmetic: naming, formatting, comment style, whitespace
• Documentation-only findings
• Finding is subjective or opinion-based
• Findings marked unvalidated at Medium/Low — not worth autonomous risk

Dismiss — when the finding is not real:

• The Verify-First Rule refutes it against the current code (record the evidence)
• Finding contradicts established project conventions (as seen in codebase)
• Finding is clearly incorrect based on context

Summary by severity and anchor:

Severity	Anchor	Default Action
🔴 Critical	75–100	Always fix
🔴 Critical	50	Defer (or ask in iteration-1 questions) — never auto-fix unverified criticals
🟠 High	75–100	Always fix
🟡 Medium	100	Fix
🟡 Medium	75	Fix if clear single fix; skip if cosmetic/subjective
🟢 Low	any	Skip unless trivial (unused imports, etc.)

Notes

• Always order findings by severity (Critical → High → Medium → Low)
• For each fix, verify the change compiles before moving on
• If a fix fails, offer alternatives (interactive) or skip with reason (auto)
• Keep track of all changes for the final summary
• If context is compacted mid-session, read .decaf/code-reviews/.resolve-state.json to resume
• Always use literal Unicode emoji characters (🔴🟠🟡🟢), never :shortcode: syntax like :yellow_circle: