cs-issue-fix

cs-issue-fix

Required reading before starting

Before making any judgment or taking any action, first run the CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not substitute reading an external AI entry point (see .codestable/reference/execution-conventions.md）。

The root cause and plan are already determined (the standard path in the analysis stage, the fast path verbally confirmed in the report stage), and your job is to change the code according to the plan, verify the effect, and write down the fix record.

What most easily goes wrong in the fix stage is not the code change itself, butthe "while I'm at it" impulses that pop up during the change—optimizing while at it, refactoring while at it, adding abstractions while at it. Each item makes sense on its own, but combined in one PR it makes it impossible for others to tell "what exactly was changed this time to fix the bug".

For shared paths and naming conventions, see .codestable/reference/shared-conventions.md Section 0 and cs-issue 's "where files go".

Run the gates (worktree + commit)

Before entering the fix, run the start gate, with{slug} being the issue directory name:

python3 .codestable/tools/codestable-worktree-gate.py --root . --json start --unit .codestable/issues/YYYY-MM-DD-{slug}

If the gate does not pass, do not start changing code; when the user approves an override, first write in the unit directory worktree-override.md（reason / scope / approval）。

After the fix is complete and before outputting the report, run the commit gate:

python3 .codestable/tools/codestable-worktree-gate.py --root . --json commit --unit .codestable/issues/YYYY-MM-DD-{slug}

If the gate does not pass, handle the findings first, and do not treat "tests passed" as done. For the installation of the gate tool and the branch-guard hook instructions, see .codestable/reference/branch-guard-hooks.md。

Two entry points

Standard path (with analysis)

Plan confirmed—read the analysis, confirm doc_type=issue-analysis and status=confirmed, which plan the user selected in Section 5
Read the context fully: the full analysis + the full report + all code located in Section 1 of the analysis + .codestable/attention.md + search the accumulation directory:
- grep -r "{关键词}" .codestable/compound/—confirm the fix approach does not violate existing library usage / patterns / research conclusions
Confirm the starting point—tell the user "I will modify {file list} according to plan X and start the fix", and only start after the user confirms

Fast path (no analysis, triggered directly from the report)

When entering this entry point, the AI has already read the code during the report stage and is confident about the root cause.

State the root cause clearly："{文件}:{行号} 's {specific code} has {problem description}", so the user can confirm the root-cause judgment is accurate
Give the fix plan—where to change, how to change (one or two sentences, do not write a full analysis document)
Only start after the user explicitly says "yes, change it this way"—"I think it's right, so I'll just change it" is not allowed
Read .codestable/attention.md
Additionally search the accumulation directory—the fast path must also check compound/(trick + explore), to avoid mistaking known boundary conditions for new problems

Constraints during implementation

Only change the files declared in the analysis

The fix scope comes from the "impact surface" of the "recommended plan" in Section 5 of the analysis. Files beyond the scope—even if they catch your eye—do not touch。

If you find something outside the scope worth changing, record a "while I'm at it finding" without changing code:

> 顺手发现：{文件:行号} {问题简述}。不在本次修复范围，可后续另开 issue。

Why so strict: code changed while at it is not in the analysis, acceptance does not match up, and git blame cannot distinguish which changes were for this bug.

Minimize the change

The fix targets only the root cause,do not introduce new abstractions, new interfaces, or new patternsIf you find that "fixing this properly requires refactoring X first" — stop and confirm with the user whether to do the refactor in this issue or split it into separate work.

Why: bug fixes are naturally narrow in scope, and introducing a new abstraction means there is only this one usage point supporting it — a classic case of premature abstraction.

Code quality reflection check

Fixing a bug looks like a small action, but AI-written fix code drifts just the same — stuffing more special handling into a large file, adding another method to a large class, adding if branches to bypass boundaries. For the reflection check, see shared-conventions.md Section 7.

issue-fix is more cautious than feature-implement:when a reflection signal is triggered but the conclusion is "this should be split", by default do not do it in this PR— record it as an incidental discovery per "minimize changes". The only exception is "the bug cannot be cleanly fixed without splitting", in which case stop and confirm with the user: "fixing this bug requires {refactor action} as a prerequisite — should it be included or split out and done separately?"

Report after completing each change

For the fix report template, see reference.md，Vague reports are not allowed. After reporting, stop and wait for the user's reply.

Verification checklist

After the fix is done, check item by item:

Reproduction steps verification— go through report Section 2 again; the problem no longer occurs
Expected behavior verification— the "expected behavior" in report Section 3 now actually happens
Blast radius regression— walk through the most basic smoke path for each "potentially affected module" in analysis Section 4
Browser verification for frontend changes(if involved) — execute per the hard requirements of .codestable/attention.md ; typecheck alone is not enough
Relevant tests pass— if tests cover the fixed area, run them

When the fix does not take effect: upgrade to log debugging

If, after going through the verification checklist, theproblem still reproducesor the behavior does not match expectations —do not keep trial-and-error on the original guess; switch to log debugging mode and re-collect runtime evidence.

Why switch: trial-and-error is essentially guessing what other possibilities exist under the original hypothesis, but if the original hypothesis is wrong, more guessing just goes in circles. Logs force you to look at actual runtime data, and often you can see at a glance where the original hypothesis went wrong.

For log debugging steps, user log-retrieval prompts, and loop limits, see reference.md。

Write {slug}-fix-note.md

After verification passes, create it in the issue directory: {slug}-fix-note.md(for the location, see cs-issue "Where do files go"), recording the full closed loop. Both the standard path template and the fast-track template are in the same directory: reference.md。

Exit conditions

All changed files are committed or listed
All items in the verification checklist are checked
{slug}-fix-note.md has been created and fully filled in
No unhandled "incidental discoveries" (all are in the follow-up issue list)
No out-of-scope changes (or they have been confirmed with the user)
The user explicitly confirms the fix is complete

Final commit

Execute per the "scoped-commit" rules in shared-conventions.md Section 4. At this stage:

Commit scope: fix code + {slug}-fix-note.md + the report / analysis updated together this time
After the fix loop is closed, tell the user "fix verification is complete,{slug}-fix-note.md has been written to disk", and immediately ask whether a commit is needed

After exiting

Tell the user: "Issue fix complete, workflow loop closed. report + analysis + fix-note have been archived."

Per shared-conventions.md Section 3 "issue-fix" closing recommendation sequence, ask one question for each (if the user says "no need", skip immediately):

After completion, first enter cs-code-review for an independent diff review; if Critical/Important are not cleared to zero, do not proceed to commit; the right to initiate scoped-commit belongs to cs-code-review。
Exposed pitfalls / long-term constraints / conventions / technical decisions → "Precipitate into compound? (cs-keep）"
This bug exposed a project-wide hard constraint / command trap / environment setup (can be explained in one or two lines, and the CodeStable skill should know it every time it starts) → "Record it in attention.md? (cs-note）"
Finally, ask whether to commit on their behalf. If agreed, execute per the closing commit rules

Suggestion: put the issue directory files and code changes in the same commit for easier tracing; for "incidentally discovered" items, open a separate cs-issue-report to handle them, don't stuff them into this PR.

If during the fix you discover the problem is actually a missing feature (not a bug) → suggest opening a separate cs-feat, don't secretly implement new features within the issue workflow.

Easy pitfalls

Declaring "fixed" after fixing without going through the verification checklist
Incidentally changing code outside the analysis scope
The fix introduces new abstractions / interfaces but you don't stop to confirm
{slug}-fix-note.md Declaring completion without having created it
Finding regression problems in the impact scope but writing "minor impact, negligible" — you must fix it until clean
For frontend changes, reporting pass after only typecheck
Ending without the user explicitly saying "fix complete"
When the fix doesn't take effect, continuing to repeatedly guess and trial-and-error on the original assumption instead of switching to log debugging
Committing after log debugging ends without cleaning up temporary logs
Not asking the user whether to commit on their behalf during closing
Without the user's explicit consent, git commit