fix

Fix Skill

Never auto-commits. All fixes are left in the working tree for user review.

Usage

/fix

No arguments required. Auto-detects the review source and fix target from session context.

Must run in the same session as the upstream review skill — /fix reads findings from session output. Exception: bug-investigation findings persist in BUGS.md and work across sessions.

---

Phase 0 — Context Detection

Examine the current session to determine which review skill ran and what the fix target is.

Detection Rules

Detect the review source using these rules in order:

Detection Method	Fix Target	Extraction
Session output contains PLAN REVIEW —	Plan file	Extract path from the header line: PLAN REVIEW — {plan_file_path}. Normalize the path (resolve .. components) and verify it falls within {memory_dir}/plans/. If the normalized path escapes that directory, set {plan_file_path_plan} to empty string (skip counter increment silently). Otherwise store as {plan_file_path_plan} for counter increment.
Session output contains CODE REVIEW — PR #	Code (PR diff)	Extract PR number from the header line: CODE REVIEW — PR #{number}
File {memory_dir}/BUGS.md exists on disk	Bug resolutions	Read BUGS.md; extract entries with **Status:** Root Cause Found

Detect memory_dir per code-quality/references/project-memory-reference.md (Directory Detection and Worktree Resolution sections).

Resolution

Scenario	Action
Exactly one source detected	Proceed with that source as fix target
Multiple sources detected	If only BUGS.md entries are found (no session-output match), use BUGS.md directly. If both a session-output match (pr-review or plan-review) AND BUGS.md entries are detected, present via AskUserQuestion: "I found findings from both [source] and BUGS.md. Which should I fix?"
No sources detected	Stop: "No review output found in this session. Run /pr-review, /plan-review, or /bug-investigation first."
Source detected but zero actionable findings	Stop: "Nothing to fix — no actionable findings in the {source} output."

Branch Alignment (pr-review only)

If the detected source is pr-review, the PR's head branch may differ from the current branch (pr-review returns to the original branch after review). Before proceeding:

1. Extract the head branch name from the pr-review session output (Branch: {head_branch} → {base_branch})
2. Verify the current branch matches the head branch (git branch --show-current)
3. If mismatch: a. Check for uncommitted changes: git status --porcelain b. If dirty: stash with git stash push -m 'fix-skill: pre-branch-align' and record the stash for later restoration (step d). If stash fails, stop with: "Working tree has uncommitted changes that cannot be stashed. Commit or stash them before running /fix." c. Checkout the head branch: git switch {head_branch} d. After Phase 5 completes (or on any error exit), return to the original branch and run git stash pop if changes were stashed. If git stash pop fails due to conflicts, inform the user: "Your changes are in git stash. Run git stash pop manually."

Confirmation

Print to the user:

Fix target: {source} — {target_description}
Actionable findings: {count}

---

Phase 0.5 — Finding Normalization

Normalize all findings from the detected source(s) into a common internal format. This phase produces a flat list of normalized findings that all subsequent phases consume.

Test Plan Discovery

Before normalizing findings, discover the plan file for the current branch and load any linked test plan. This follows the same branch-header matching algorithm as /swarm Phase 4 and /quality-gate Step 0:

1. Get the current branch: git branch --show-current
2. Search {memory_dir}/plans/ for plan files whose **Branch:** header field matches the current branch. Fall back to branch-slug prefix matching if no header match is found. Use the most recent by unix timestamp if multiple match. Normalize the discovered path (resolve .. components) and verify it falls within {memory_dir}/plans/. If the normalized path escapes that directory, set {plan_file_path_pr} to empty string (skip counter increment silently). Otherwise store as {plan_file_path_pr} for counter increment. If no plan file is found, {plan_file_path_pr} is empty string.
3. If a plan file is found and it contains a ## Test Plan section, extract the **Test Plan:** path annotation from that section.
4. Normalize the path (resolve .. components) and verify it falls within {memory_dir}/test-plans/. If the normalized path escapes that directory, set {plan_test_plan} to empty string and log a warning: "Warning: test plan path escapes {memory_dir}/test-plans/ boundary — setting {plan_test_plan} to empty string."
5. If the path is valid but the file does not exist, set {plan_test_plan} to empty string (graceful fallback — no warning).
6. If the path is valid and the file exists, read the file and store its content as {plan_test_plan}.
7. If no plan file is found, or no ## Test Plan section exists, set {plan_test_plan} to empty string.

{plan_test_plan} is available to all subsequent phases (Phase 1 triage and Phase 2 investigator dispatch).

Common Finding Schema

Each normalized finding tracks:

• id — generated identifier using pattern {source-prefix}-{category-abbrev}-{N}:
  • pr-review prefix: pr (e.g., pr-test-1, pr-sec-2, pr-corr-3)
  • plan-review prefix: pl (e.g., pl-feas-1, pl-rsch-2, pl-arch-3)
  • bug-investigation prefix: BUG (e.g., BUG-001, matching the BUGS.md entry number)
• source — one of: pr-review | plan-review | bug-investigation
• classification — always needs-fix (see note below on needs-input)
• category — the category section heading from the upstream output (e.g., TESTING GAPS, RESEARCH GAPS, CORRECTNESS)
• location — file:line for code findings, plan section name for plan findings, BUG-NNN for bug entries
• description — the finding text as written in the review output
• evidence — the reviewer's evidence line from the review output
• suggested_fix — null for pr-review and plan-review (not present in terminal output); the Resolution Plan checklist items for bug-investigation entries
• is_research_gap — true if (a) the finding appears under the RESEARCH GAPS category section OR has a [Reviewer] tag of Unknown Unknowns (plan-review — structural match on category + reviewer tag, not keyword matching), or (b) the finding description contains the literal string Recommended resolution: /deep-research (pr-review — see source-specific rule below).
• verifier_verdict — "needs_context" if from the upstream Needs Context section, otherwise null
• spike_question — the specific assumption to verify, extracted from the finding text. Populated only when is_research_gap == true AND source == plan-review. Null for pr-review research gaps (pr-review findings go to standard investigators, not spike investigators). Extraction rule: if the finding contains a question sentence (ends with ?), use it verbatim. Otherwise, reformulate the finding's core assumption as a yes/no question.
• plan_context — surrounding plan text (5-10 lines around the affected section). Populated only when is_research_gap == true AND source == plan-review. Null for pr-review research gaps (no plan exists — the finding references code, not a plan section).

Source-Specific Normalization

pr-review findings:

Categories (in display order): Testing Gaps, Correctness, Security, Architecture, Decisions Needed, Performance, Style & Conventions. Extract all findings from each category section. Also extract findings from the ─── Needs Context ─── section with verifier_verdict: "needs_context". For Needs Context findings, map the Investigation: {investigation_summary} field to evidence (these use Investigation: instead of Evidence: in the upstream output). Skip findings in the Deferred section — these were explicitly deferred by the user during the upstream review and should not be re-processed. Set is_research_gap: true if the finding description contains the literal string Recommended resolution: /deep-research. This format is emitted by any domain reviewer's third-party technology gap checklist item when the gap cannot be resolved from codebase context alone.

Category abbreviations for IDs: test, corr, sec, arch, dec, perf, style.

plan-review findings:

Categories (in display order): Research Gaps, Feasibility, Scope, Dependencies, Architecture, Security, Specification. Extract all findings from each category section. Also extract findings from the ─── Needs Context ─── section with verifier_verdict: "needs_context". For Needs Context findings, map Investigation: {investigation_summary} to evidence. Set is_research_gap: true per the structural rules above (category = RESEARCH GAPS, OR reviewer tag = Unknown Unknowns) — not by scanning description text. Skip findings in the Deferred section — these were explicitly deferred by the user during the upstream review and should not be re-processed.

Category abbreviations for IDs: rsch, feas, scope, dep, arch, sec, spec.

bug-investigation findings:

Read {memory_dir}/BUGS.md directly (do not rely on session output). Extract all ## BUG-NNN entries whose **Status:** field is Root Cause Found or Fix Ready. All bug entries are needs-fix by definition — a bug at these statuses has a known root cause and is ready to fix. The suggested_fix field maps to the entry's ### Resolution Plan checklist.

Note on needs-input

Upstream skills (pr-review, plan-review) resolve ALL needs-input findings via AskUserQuestion before producing terminal output. By the time this skill runs, all findings visible in the terminal output are actionable. Normalize all of them as needs-fix. Do not re-classify or re-triage based on description text.

---

Phase 1 — Triage, CWD Validation, and Scope Assessment

Step 1a: CWD Boundary Validation

Resolve all finding locations to absolute paths. Normalize paths first: collapse ../ and ./ sequences without resolving symlinks. Then verify the normalized path falls within the project root. Any path that falls outside the current project root is out_of_scope — mark it and exclude it from investigation and implementation (Phases 2–3). Never pass out-of-scope paths to investigators or fixers. Retain out-of-scope findings in total_findings_in for Phase 4 verification accounting.

Symlink limitation: This check validates the textual path, not symlink targets. A symlink inside the project that points outside it would pass this check. When a path cannot be confidently resolved within the project (e.g., it traverses a symlink whose target is unknown), treat it as out_of_scope rather than proceeding on ambiguous paths.

Step 1b: Triage Assessment

Assess each finding and assign a triage label:

Assessment	Criteria	Action
Direct fix	Clear description, unambiguous location, no architectural decisions required	Queue for Phase 2 investigation
Spike execution	is_research_gap == true AND source == plan-review	Queue for Phase 2 spike investigation
Research-enriched fix	is_research_gap == true AND source == pr-review	Queue for Phase 2 — standard investigation after /deep-research enrichment
Needs refinement	Multiple valid approaches, UX implications, or architectural tradeoffs that cannot be resolved without user input	Queue for Phase 2 (marked for user confirmation before implementation)
Needs plan	Any finding touching 5+ files OR requiring architectural redesign beyond localized changes	Recommend /incremental-planning; skip this finding
Out of scope	Path outside CWD (identified in Step 1a)	Skip with note
UAT validation	{plan_test_plan} is non-empty AND finding's category is one of TESTING GAPS, CORRECTNESS, or SCOPE	Queue for Phase 2 — investigator receives {plan_test_plan} context to check implementation against UAT scenarios
Unverified	verifier_verdict == "needs_context"	Queue for Phase 2 — investigator will attempt to verify before fixing

PR Scope Anchoring (pr-review source only)

"Out of scope" applies ONLY to paths outside CWD (Step 1a). It does NOT apply to findings about code introduced by the PR. The scope boundary is the PR diff, not the upstream review's finding list. If the review missed an issue but the code was introduced by the PR, it is in scope for /fix. Investigators who discover additional issues during investigation in PR-introduced code should report them as resolution — not dismiss them as "out of scope because the review didn't flag it." The review is not exhaustive; that is why investigation exists.

Step 1c: Triage Summary

Present the triage summary to the user before proceeding:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FIX TRIAGE — {source} — {target_description}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Direct fix ({count}):
  {id}: {description} [{location}]
  ...

Spike execution ({count}):
  {id}: {description} [{location}]
  ...

Research-enriched fix ({count}):
  {id}: {description} [{location}] — /deep-research before investigation
  ...

Needs refinement ({count}):
  {id}: {description} — will confirm approach before implementing
  ...

Needs plan ({count}):
  {id}: {description} — recommend /incremental-planning
  ...

Out of scope ({count}):
  {id}: {description} — outside project root, skipped
  ...

UAT validation ({count}):
  {id}: {description} — investigator will check implementation against UAT scenarios
  ...

Unverified ({count}):
  {id}: {description} — will attempt verification in investigation
  ...

Proceeding with {actionable_count} findings ({direct_fix_count} direct +
{spike_count} spikes + {needs_refinement_count} needing refinement +
{uat_count} UAT validation + {unverified_count} unverified).
Skipping {skip_count} ({needs_plan_count} needs-plan + {oos_count} out-of-scope).
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Omit sections with zero findings.

---

Phase 2 — Parallel Investigation

Dispatch background investigator agents for all queued findings. Investigators are read-only — they produce structured results that the lead uses in Phase 3 to implement fixes.

Grouping Rules

Before dispatch, group findings by source and location to minimize agent count:

Source	Grouping rule
pr-review (code, is_research_gap == false)	Group by file path — all findings targeting the same file go to one agent
pr-review (research gap, is_research_gap == true)	Group by file path like code findings, but dispatch AFTER /deep-research completes — the Lead appends research report content to each finding's evidence field before constructing the standard investigator prompt
plan-review (non-spike)	Group ALL non-spike plan findings into one agent — they all target the same plan file
plan-review (spike, is_research_gap == true)	One agent PER finding — do NOT group spikes; parallel execution is more valuable than shared context
bug-investigation	One agent per BUG-NNN entry

Agent Dispatch

For each group of code, plan, or bug findings, spawn one standard investigator:

Agent(
  description="Investigate {N} finding(s) in {file/section/BUG-NNN}",
  subagent_type="general-purpose",
  model="sonnet",
  mode="bypassPermissions",
  run_in_background=true,
  prompt=<standard investigator template from code-quality/skills/fix/references/investigator-prompt.md,
          with one <finding-data> block per finding in the group>
)

For each spike finding (is_research_gap == true AND source == plan-review), spawn one spike investigator:

Agent(
  description="Spike: {brief description of what to verify}",
  subagent_type="general-purpose",
  model="sonnet",
  mode="bypassPermissions",
  run_in_background=true,
  prompt=<spike investigator template from code-quality/skills/fix/references/investigator-prompt.md,
          with the finding's spike_question and plan_context fields populated;
          when no /deep-research was run for this spike, omit the RESEARCH CONTEXT section
          (the block from "RESEARCH CONTEXT (pre-fetched..." through the placeholder line)
          entirely — do not leave a literal {RESEARCH_CONTEXT} placeholder in the prompt>
)

UAT validation findings use the standard investigator dispatch path (same grouping rules as code or plan findings). When one or more findings in a group are tagged UAT validation, include the {plan_test_plan} content in the ## UAT Context section of the standard investigator prompt. If no findings in the group are UAT validation, omit that section entirely — do not leave a literal {plan_test_plan} placeholder in the prompt. Do NOT dispatch a separate agent for UAT validation findings; they share the standard investigator agent with other findings from the same file or plan section.

mode="bypassPermissions" is required — investigators run in background and cannot prompt for permissions interactively. The read-only constraint is prompt-enforced, not technically enforced — bypassPermissions grants full tool access. The prompt instruction "You MUST NOT edit, write, or delete any files" is the primary control; the lead reviewing all results before acting is the secondary defense. This matches the trust model used by bug-investigation's background agents.

Sanitization: Before constructing investigator prompts, strip or escape any literal delimiter sequences in all finding field values (description, evidence, suggested_fix, location, spike_question, plan_context) and in RESEARCH_CONTEXT content (if included):

• </finding-data> → </finding-data>
• <finding-data → <finding-data
• <!-- → <!--

This prevents finding and research content from escaping the untrusted data boundary (the <!-- END OF FINDING DATA --> marker) used to separate untrusted data from investigator instructions.

• Third-party research gaps — When any finding has is_research_gap == true and names a third-party library, API, or service: dispatch non-research-gap investigators first (they run in background). Then invoke /deep-research via the Skill tool. Extract the research question from the finding: for pr-review, parse the targeting [specific question] suffix from the Recommended resolution: format; for plan-review, use spike_question. Use External mode if the finding is about a technology not present in the codebase, or Bridged mode if it involves how the current codebase uses a third-party component. After /deep-research completes, read the resulting report. Routing depends on source:
  • plan-review findings: pass the report as {RESEARCH_CONTEXT} in the spike investigator prompt (see spike dispatch above)
  • pr-review findings: append the report content to the finding's evidence field, then dispatch via the standard investigator (code grouping rules apply — see grouping table) This replaces ad-hoc WebSearch calls with the structured 5-hop, 40+ source methodology. If multiple findings name different third-party technologies, batch them into a single /deep-research invocation with a combined research question.

Dispatch all agents in parallel. Wait for all to complete before proceeding.

In practice, upstream reviewers produce 5-15 findings. With file-based grouping, this typically results in 3-10 investigator agents — well within Claude Code's concurrency limits.

Collecting and Routing Results

After all investigators complete, route each result by verdict:

Verdict	Action
resolution	Queue for Phase 3 implementation
refinement_needed	For each finding, present its options via AskUserQuestion (single-select — options are mutually exclusive). User picks an option → queue selected approach for Phase 3. User declines → record as user-deferred.
invalid	Remove from fix queue; note in final report
spike_confirmed	Queue plan update for Phase 3
spike_partial	Queue plan update with partial evidence for Phase 3; note evidence gaps in report
spike_invalidated	Present to user via AskUserQuestion with three options: (1) Update plan with corrected information, (2) Skip — address during implementation, (3) Defer to /incremental-planning for replanning
uat_validated	Route to findings_fixed bucket — UAT scenario confirmed
uat_mismatch	Present mismatch to user via AskUserQuestion with scenario name, expected vs found. User chooses fix → findings_fixed; user defers → user-deferred
Agent failure (timeout, crash, empty output, or unparseable response)	Record all findings assigned to that agent as blocked with reason "investigator agent failed"; note in report

AskUserQuestion unavailable fallback: If AskUserQuestion is unavailable (non-interactive environment), record all refinement_needed, spike_invalidated, and uat_mismatch findings as user-deferred with reason "non-interactive — AskUserQuestion unavailable". For spike_invalidated findings, also preserve the spike verdict and plan impact details in the reason field so they surface in the Phase 5 DEFERRED section.

LoE escalation: If an investigator estimates a finding's LoE as significant AND returned verdict refinement_needed, include the LoE context in the AskUserQuestion presentation. If the investigator returned resolution despite significant LoE, proceed with the resolution — the investigator already determined a clear fix. Flag all significant LoE findings in the Phase 5 report regardless of verdict.

Handling unverifiable findings: If an investigator receives a finding with verifier_verdict: "needs_context" and cannot verify it (insufficient evidence to confirm or deny), it returns verdict invalid with reason "could not verify — insufficient evidence". The lead routes this to the unverified_unresolved bucket (not findings_invalid).

UAT validation verdict routing: For UAT validation findings, investigators return one of two explicit verdict types:

• uat_validated: The UAT scenario was verified through code inspection or test execution — the implementation matches the UAT scenario expectations. Lead routes to findings_fixed bucket.
• uat_mismatch: The implementation differs from UAT scenario expectations — present the specific mismatch to the user via AskUserQuestion with the scenario name, what was expected, and what was found.

Conflict Detection

After all investigators complete, scan all resolution verdicts for overlapping locations: two or more resolutions targeting the same file and overlapping line ranges. Compatible overlaps (different lines, no shared context) are handled sequentially in Phase 3 — if applying a resolution fails because the target code has already been modified by a prior fix, re-read the file and adapt the resolution. Incompatible overlapping resolutions (contradictory changes to the same lines) cannot be applied automatically — present the conflict to the user via AskUserQuestion and ask which resolution takes precedence.

---

Phase 3 — Sequential Implementation

The lead implements all fixes sequentially, in file order (minimize context switching between files).

Pre-Implementation Check

Before implementing any fixes, run git status --porcelain to verify the working tree is in the expected state. If unexpected modifications are detected (files changed during Phase 2 by an investigator agent despite the prompt constraint), warn the user and confirm before proceeding.

Implementation Protocol

For each queued finding, in order:

1. Read the target file (always re-read before editing — prior fixes may have changed line numbers).

2. Apply the exact resolution from the investigator's Investigation Result.

3. Plan-review fixes (non-spike): Edit the plan file — task descriptions, missing steps, ordering corrections.

4. Plan-review spike fixes: Edit the plan file to incorporate spike results:

   • spike_confirmed → replace the open question or assumption with the resolved evidence
   • spike_invalidated → update the plan per the user's choice from Phase 2 (update / skip / replan)
   • spike_partial → update with verified parts; mark remaining open questions explicitly in the plan

5. Code fixes: Edit source files. Run tests after completing all edits to a single file (not after each finding — batch per file).

6. Bug fixes: Implement the resolution plan steps from BUGS.md. After implementation, update the entry's **Status:** field to "Fix Ready". The user verifies the fix manually and updates to "Fixed" when confirmed.

   Use a targeted Edit replacing only the **Status:** Root Cause Found (or current status) line with **Status:** Fix Ready — do not reconstruct or rewrite the surrounding metadata block. This preserves adjacent fields like **Tracked In:**.

Test Execution

After all code changes to a file (skip for plan-only or BUGS.md-only changes):

Detection order for the test command:

1. CLAUDE.md — look for a make test or explicit test command
2. Makefile — check for a test target
3. Language-specific default — pytest (Python), jest (JS/TS), go test ./... (Go)
4. Skip with note if none detected

Test failure → revert all changes to that file (git checkout -- <file>), record ALL co-located findings as blocked in the report. Do not retry with alternative fixes — blocked findings surface in the Phase 5 report for user attention.

Blast radius: File-level revert is intentionally conservative. If 3 findings target the same file and the 3rd breaks tests, reverting the file also undoes valid fixes #1 and #2 — all 3 are recorded as blocked. This is by design: when tests fail after batched edits, the failing change cannot be isolated without per-finding rollback (significantly more complex). The investigator's resolution quality is the primary defense. Additionally, if the file had pre-existing unstaged changes before /fix ran, those are also reverted. Run git stash before invoking /fix if uncommitted work exists.

Cross-Cutting Fixes

Apply in dependency order per the investigator's instructions. If investigator did not specify order, apply in the order: interface/type definitions → callers → call sites → tests.

Commit Behavior

Do NOT commit. Leave all changes in the working tree for user review.

---

Phase 4 — Verification

Apply the Verification Protocol from code-quality/references/finding-classification.md, extended with 7 outcome buckets to cover all standalone /fix outcomes.

Outcome Buckets

Bucket	What it contains
total_findings_in	All findings after Phase 0.5 normalization
findings_fixed	Successfully implemented (including spike-resolved plan updates)
findings_invalid	Investigator returned invalid verdict (finding no longer applies)
user-deferred	User declined via refinement prompt or conflict resolution choice
needs_plan	Recommended for /incremental-planning (too large for direct fix)
out_of_scope	Outside CWD — excluded in Phase 1a
blocked	Test failure prevented fix
unverified_unresolved	needs_context findings that the investigator also could not resolve

Category Mapping

Outcome	Bucket
Direct fix implemented	findings_fixed
Spike confirmed (plan updated)	findings_fixed
Spike partial (plan updated)	findings_fixed
Spike invalidated (user chose plan update)	findings_fixed
Spike invalidated (user chose replan)	needs_plan
Spike invalidated (user chose skip)	user-deferred
Needs refinement (implemented after guidance)	findings_fixed
Needs refinement (user declined)	user-deferred
Needs plan	needs_plan
Out of scope	out_of_scope
Investigator returned invalid (finding no longer applies)	findings_invalid
Investigator returned invalid (could not verify — unverified finding)	unverified_unresolved
Test failure prevented fix	blocked
Agent failure (investigator crashed, timed out, or returned unparseable output)	blocked
Unverified, investigator confirmed valid	route through normal triage (direct fix / needs refinement / etc.)
Unverified, investigator could not resolve	unverified_unresolved
UAT validated (uat_validated verdict)	findings_fixed
UAT mismatch — user chose fix implementation	findings_fixed
UAT mismatch — user chose defer	user-deferred

Verification Check

total_findings_in == findings_fixed + findings_invalid + user-deferred
                   + needs_plan + out_of_scope + blocked + unverified_unresolved

If delta > 0: list the missing finding IDs as UNACCOUNTED in the Phase 5 report.

---

Phase 5 — Terminal Output

Print the structured fix report:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FIX REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Source: {source}
Fix target: {target_description}
Findings: {total_in} total → {fixed} fixed (incl. {spike_count} spikes), {invalid} invalid,
  {deferred} deferred, {plan} needs-plan, {oos} out-of-scope,
  {blocked} blocked, {unresolved} unresolved

FIXED ({count})
  1. [{id}] {description}
     {file}:{line_range} — {what was changed}

  ── Spike Detail ({count}) ──
  1. [{id}] {description}
     Result: {verdict} — {evidence summary}
     Plan updated: {section}
     Evidence gaps: {what could not be verified} (spike_partial only)

INVALID ({count})
  1. [{id}] {description}
     Investigator: {reason}

BLOCKED ({count})
  1. [{id}] {description}
     Reason: {test failure}

DEFERRED ({count})
  1. [{id}] {description}
     Reason: {why}

NEEDS PLAN ({count})
  1. [{id}] {description}
     Recommended: /incremental-planning

OUT OF SCOPE ({count})
  1. [{id}] {description}
     {file} — outside working directory

UNRESOLVED ({count})
  1. [{id}] {description}
     Neither upstream verifier nor investigator could confirm — requires human judgment

UNACCOUNTED ({count} — if any)
  1. [{id}] {description}
     WARNING: Not processed

Verification: {total_in} in → {sum} accounted [PASS | FAIL]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Omit sections with zero count.

Post-Fix Suggestion

After the report, print context-appropriate suggestions (show all that apply, one per line):

Condition	Suggestion
Code changes were made	Fixes applied. Consider running /quality-gate to verify.
Plan-only changes	Plan updated. Consider running /plan-review to verify the changes.
Spikes invalidated assumptions	Spikes invalidated {N} assumption(s). Review updated plan sections carefully — consider /plan-review to verify.
BUGS.md was updated	Bug fixes applied. BUGS.md entries updated to 'Fix Ready'. Verify manually and update to 'Fixed' when confirmed.

Counter Increment

After the Post-Fix Suggestion, increment the appropriate lifecycle counter on the plan file.

1. Determine the source that was fixed (use the final resolved fix source from Phase 0 — in multi-source cases this is the user-selected source, not the initial detection result):
   • If source was PLAN REVIEW — → increment fix-cycle
   • If source was CODE REVIEW — PR # → increment pr-fix-cycle
   • If source was BUGS.md → skip counter increment (no plan file linkage)
2. Locate the plan file — reuse the path already discovered, do not re-run discovery:
   • For plan-review source: use {plan_file_path_plan} stored in Phase 0
   • For pr-review source: use {plan_file_path_pr} stored in Phase 0.5
   • If the relevant variable is empty, skip counter increment silently
3. Re-read the plan file using the path from step 2 (do not re-discover), find the **Iterations:** block
4. Read the current counter value N from the line for the counter identified in step 1 (- fix-cycle: {N} for plan-review source, - pr-fix-cycle: {N} for pr-review source)
5. Verify N is a non-negative integer (digits only, e.g. 0, 1, 12). If N is not a valid integer, skip the increment silently
6. Increment the appropriate counter by 1:
   • plan-review source: use Edit to replace - fix-cycle: {N} with - fix-cycle: {N+1}, where {N} is the actual integer read in step 4
   • pr-review source: use Edit to replace - pr-fix-cycle: {N} with - pr-fix-cycle: {N+1}, where {N} is the actual integer read in step 4
7. If no **Iterations:** block found, skip silently

---

Relationship to Other Skills

Skill	Relationship
code-quality:pr-review	Produces findings that /fix acts on. Run /pr-review first, then /fix.
code-quality:plan-review	Produces plan findings that /fix acts on. /fix edits the plan file only. For Research Gaps and Unknown Unknowns, /fix executes actual spikes to verify assumptions.
code-quality:quality-gate	Not a source — quality-gate fixes findings inline. /fix suggests /quality-gate after code fixes for verification.
code-quality:bug-investigation	Documents bugs with root causes and resolution plans. /fix implements resolution plans or recommends /incremental-planning for complex bugs.
code-quality:incremental-planning	Recommended by /fix when a bug resolution requires significant scope, or when a spike invalidates a plan assumption requiring replanning.
code-quality:swarm	Swarm has its own internal Fixer (Phase 5). /fix is the standalone equivalent for non-swarm workflows.

---

Quick Reference

### Flow
Phase 0: Context Detection → Phase 0.5: Normalize → Phase 1: Triage + CWD Validation →
Phase 2: Investigate ALL findings (background, pre-implementation) →
Conflict Detection → Phase 3: Implement (lead, sequential, file order) →
Phase 4: Verify → Phase 5: Report

### Fix Target Rules
plan-review findings        → edit plan file ONLY (never implement code)
plan-review Research Gaps   → RUN spikes, then update plan with resolved evidence
pr-review findings          → edit code on PR branch
bug-investigation findings  → implement resolution OR recommend /incremental-planning

### Not Supported
quality-gate → excluded (fixes findings inline, reports only aggregates)