cs-issue-fix

At this stage, the root cause and solution have been confirmed (for the standard path, it is in

{slug}-analysis.md

; for the fast track, it was confirmed verbally during the report phase). Your tasks are to modify the code according to the solution, verify the results, and write down the fix records.

It sounds straightforward, but the biggest problem in the fix stage is not the code modification itself, but the "incidental" impulses that arise during the process —— incidentally optimizing a bit, incidentally refactoring a little, incidentally adding an abstraction. Each item makes sense on its own, but when combined in one PR, others can't tell "what exactly was changed to fix this bug". The purpose of all the following rules is to stop such impulses.

For shared paths and naming conventions, see Section 0 of
codestable/reference/shared-conventions.md
and the "Where to place files" section of
cs-issue
.

Two Entry Points

Standard Path Entry (with {slug}-analysis.md)

Root cause analysis exists and solution is confirmed —— Read
```
{slug}-analysis.md
```
, confirm that the frontmatter has
```
doc_type=issue-analysis
```
and
```
status=confirmed
```
, and check which solution the user selected in Section 5 "Fix Solution"
Read all context:
- Full root cause analysis document
- Full issue report document
- All code files located in Section 1 of the root cause analysis
- ```
AGENTS.md
```
- Relevant records in the沉淀 directory (search uniformly in
```
codestable/compound/
```
  , filter by
```
doc_type
```
  as needed):
  - Trick search:
    python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter status=active --query "{issue keywords}"
    —— Confirm that the fix method does not violate existing library usage / pattern suggestions
  - Explore search:
    python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=explore --query "{issue keywords}"
    —— Confirm that the fix point does not conflict with existing evidence
Confirm the starting point of the fix —— Tell the user "I will modify {file list} according to Solution X and start the fix", and wait for the user's confirmation before taking action

Fast Track Entry (without {slug}-analysis.md, triggered directly from cs-issue-report)

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

Clearly state the root cause to the user: "The {specific code} at
```
{file}:{line number}
```
has {problem description}", and ask the user to confirm the accuracy of the root cause judgment
Provide a fix solution —— Where to modify and how to modify (just one or two sentences, no need to write a complete analysis document)
Wait for the user to explicitly say "Yes, modify it this way" before taking action —— "I think it's correct, so I'll modify it directly" is not allowed
Read
```
AGENTS.md
```
Supplement search in the沉淀 directory —— For the fast track, also use
```
search-yaml.py --dir codestable/compound
```
to search, check similar tricks with
```
--filter doc_type=trick
```
, and avoid mistaking known boundary conditions for new issues with
```
--filter doc_type=explore
```

Constraints During Implementation

Only Modify Files Stated in the Root Cause Analysis

The scope of the fix comes from the "Impact Scope" in Section 5 "Recommended Solution" of

{slug}-analysis.md

. Do not modify files outside the scope —— even if they look problematic.

If you find something worth modifying outside the scope, record it as an "Incidental Finding" and do not modify the code:

markdown

> Incidental Finding: {problem brief} at {file:line number}. Not within the scope of this fix, can open a separate issue later.

Why is this so strict? The reason is the same as feature-implement —— code modified incidentally is not included in the analysis, so it cannot be verified during acceptance, and future developers cannot distinguish which changes were made to fix this bug via git blame.

Minimize Changes

The fix changes should only target the root cause, do not introduce new abstractions, new interfaces, or new patterns. If you find that "to fix this properly, I need to refactor X first" —— stop and confirm with the user whether to do the refactoring in this issue or split it into independent work.

Why is this so strict? Bug fixes are inherently narrow-scoped actions. Introducing a new abstraction means this abstraction is only supported by this single usage point —— a typical case of premature abstraction. Either refactor first then fix the bug, or fix the bug then refactor separately, but do not do both in one PR.

Code Quality Reflection Check

Although bug fixes seem like small actions, AI can still drift when writing fix code —— adding a special handling section to an already long file, adding another method to an already heavy class, adding an

if

branch to bypass a certain boundary condition. For reflection checks, see Section 7 of

codestable/reference/shared-conventions.md

In the issue-fix stage, this section requires more caution than feature-implement: when a reflection signal is triggered and the conclusion is "should split", do not do it in this PR by default —— record it as an incidental finding according to the "minimize changes" logic, and handle it in separate work later. The only exception is "cannot fix this bug cleanly without splitting", then stop and explicitly tell the user "The prerequisite for fixing this bug is {refactoring action}, should we include it or split it into separate work?"

Report After Completing Each Change

The fix report template is in

reference.md

in the same directory, vague reports are not allowed. Stop and wait for the user's reply after reporting.

Verification Checklist

After modifying the fix code, check each item in the report:

Reproduction Step Verification: Follow the steps in Section 2 of
```
{slug}-report.md
```
; the issue no longer occurs
Expected Behavior Verification: The "Expected Behavior" described in Section 3 of
```
{slug}-report.md
```
now occurs
Impact Scope Regression: "Potentially Affected Modules" in Section 4 of
```
{slug}-analysis.md
```
—— Run the most basic smoke test for each module to confirm no new issues are introduced by the fix
Frontend Change Browser Verification (if applicable): Mandatory requirement in AGENTS.md, cannot rely solely on typecheck
Relevant Tests Pass: If there are tests covering the fix area, run them

When the Fix Does Not Take Effect: Upgrade to Log Debugging

If after going through the verification checklist, you find that the issue still reproduces or the behavior does not match expectations, do not repeatedly trial and error based on the original guess —— switch to log debugging mode and re-collect runtime evidence.

Why switch? Repeated trial and error is essentially guessing what else is possible under the original hypothesis, but if the original hypothesis is wrong, more guesses will only go in circles. Logs will force you to look at actual runtime data, which often reveals where the original hypothesis was wrong at a glance.

Log debugging steps, user prompts for retrieving logs, and cycle limits are in

reference.md

in the same directory.

Write {slug}-fix-note.md

After verification passes, create

{slug}-fix-note.md

in the issue directory (location see the "Where to place files" section of

cs-issue

) to record the complete closure of this fix. Both standard path and fast track templates are in

reference.md

in the same directory.

Exit Conditions

All modified files have been submitted or listed
All items in the verification checklist are checked
```
{slug}-fix-note.md
```
has been created and fully filled (use the standard template for the standard path, fast track template for the fast track)
No unprocessed "Incidental Findings" (all have been added to the follow-up issue list)
No changes outside the scope (or confirmed with the user)
User explicitly confirms the fix is complete

Final Commit

Follow the rules in Section 4 "Final Commit (scoped-commit)" of

codestable/reference/shared-conventions.md

. Specific points for this stage:

Commit Scope: Fix code,
```
{slug}-fix-note.md
```
, and
```
{slug}-report.md
```
/
```
{slug}-analysis.md
```
that were actually updated together this time
After the fix is closed, tell the user "Fix verification is completed,
```
{slug}-fix-note.md
```
has been archived", then immediately ask if a commit is needed

After Exit

Tell the user: "Issue fix is completed, workflow is closed. Issue report ({slug}-report.md) + root cause analysis ({slug}-analysis.md) + fix record ({slug}-fix-note.md) have been archived."

Then ask one sentence each in the recommended closing order for "issue-fix" in Section 3 of

codestable/reference/shared-conventions.md

(skip immediately if the user says "No"):

This fix exposed a pitfall / experience worth reusing → "Do we need to document this pitfall as a learning document? (Follow
```
cs-learn
```
, will be written to
```
codestable/compound/
```
)"
This fix resulted in long-term constraints, conventions, or technical decisions → "Do we need to archive this decision? (Follow
```
cs-decide
```
)"
Finally, ask again if you need to commit this fix on behalf of the user. When the user agrees, follow the final commit rules until the commit is completed.

You can suggest:

Include the files in the issue directory and code changes in the same commit for easy future tracing
Handle follow-up issues for "Incidental Findings" in a new round of
```
cs-issue-report
```
, do not include them in this PR

If during the fix you find that the issue is actually a feature gap (not a bug), suggest the user open a separate

cs-feat

workflow to handle it, do not secretly implement new features in the issue workflow.

Common Pitfalls

Declare "Fixed" without going through the verification checklist after modifying the code
Incidentally modified code outside the scope of the root cause analysis
Introduced new abstractions / interfaces during the fix but did not stop to confirm with the user
Declared the workflow completed without creating
```
{slug}-fix-note.md
```
Found regression issues in the impact scope but wrote "Minor impact, can be ignored" in the report —— fix until it's clean
Made frontend changes but did not run in the browser, only did typecheck and reported success
Ended the workflow without the user explicitly saying "Fix completed"
When the fix did not take effect, continued to guess and trial and error based on the original hypothesis instead of switching to log debugging
Submitted code without cleaning up temporary log statements after log debugging
Did not ask the user if you need to commit on their behalf during workflow closing
Directly ran
```
git commit
```
without the user's explicit consent

cs-issue-fix

NPX Install

Tags

SKILL.md Content (Chinese)

cs-issue-fix

Two Entry Points

Standard Path Entry (with {slug}-analysis.md)

Fast Track Entry (without {slug}-analysis.md, triggered directly from cs-issue-report)

Constraints During Implementation

Only Modify Files Stated in the Root Cause Analysis

Minimize Changes

Code Quality Reflection Check

Report After Completing Each Change

Verification Checklist

When the Fix Does Not Take Effect: Upgrade to Log Debugging

Write {slug}-fix-note.md

Exit Conditions

Final Commit

After Exit

Common Pitfalls