3_fix

Fix issues found in a review report.

Steps:

1. Read CLAUDE.md — note the project's test command, lint command, build command, and typecheck command if listed

2. If $ARGUMENTS is provided, read .claude/reviews/<name>-review.md. Otherwise read the most recently modified file in .claude/reviews/

3. If a corresponding spec exists in .claude/specs/, read it too — fixes must stay within the spec's stated requirements a. Phase awareness: if .claude/specs/<name>-phases.md exists, read it. Fixes must stay within the current phase's scope. If a review issue references a requirement that belongs to a later (pending) phase, skip it with "out of scope for current phase" — do not implement it.

4. Parse the Issues section — work through them in order of severity: critical first, then major, then minor

5. Circuit breaker: for each issue, check whether it appeared in a previous review of the same spec. If the same issue has recurred across two or more review cycles, flag it as a recurring failure, stop fixing, and escalate to the user with a description of the root cause — do not attempt a third fix for the same problem without user guidance.

6. Scope gate: only touch files that are explicitly mentioned in the Issues section of the review report. For each issue: read the affected file, understand the problem, then apply a minimal fix — do not refactor, clean up, or improve any code outside those files. Unrelated issues belong in the next review cycle, not this fix cycle.

7. After fixing all issues, run the project's verify commands in this order (read them from CLAUDE.md, skip any not listed): a. Typecheck b. Lint c. Tests d. Build (if listed)

8. If any verify step fails, fix those failures too. If a verify step still fails after two fix attempts, stop and escalate to the user — do not loop.

9. Validation criteria check: if the spec has a "Validation criteria" section, confirm each criterion is still met after the fixes — list each criterion and its status. Any failing criterion is a new critical issue that must be fixed before continuing. (In phased mode, only check criteria assigned to the current phase.)

10. Self-check against review items: before declaring done, re-read the review file and verify each issue one by one: a. For each issue marked in the review, re-read the affected file at the specific line b. Confirm the fix actually addresses the issue described — not just a nearby change c. Check that the fix didn't introduce a new problem in the same area (e.g. breaking an import, changing a signature without updating callers) d. If any issue is NOT actually resolved, fix it now before proceeding This step prevents the common pattern where /3_fix reports "all fixed" but the next /2_review finds the same issues still present.

11. Spec-anchored check: review whether any fixes diverged from the spec's stated requirements. If they did, do not update the spec — the spec is ground truth. Instead, document the divergence in the report (step 13) and flag it for user decision. Only the user may approve spec changes.

12. Self-improvement gate: for each fixed issue, ask whether a rule would prevent recurrence. If yes, write it to .claude/context/lessons.md immediately using this format:

    ## YYYY-MM-DD — <topic>
    **scope:** framework | project
    
    **What went wrong**: ...
    **Rule**: ...
    

    Scope guidelines:

    • scope: framework — the lesson applies to any project using this framework (e.g., "never skip typecheck", "circular import prevention"). These can graduate to CLAUDE.md rules via /ship Step 4b.
    • scope: project — the lesson is specific to the current codebase (e.g., "HelpSection goes below panel header", "Likert zero-value bug"). These stay in lessons.md and are stripped by /deploy.

    When in doubt, use scope: project — it's safer to under-promote than to pollute the framework with project-specific rules. Also flag it in the report so the team can consider promoting it to CLAUDE.md.