cs-issue-fix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cs-issue-fix

到这一步根因和方案已经确定（标准路径在

{slug}-analysis.md

里、快速通道在 report 阶段口头确认过），你的活是按方案改代码、验证效果、写下修复记录。

听起来直白，但 fix 阶段最容易出问题的不是改代码本身，而是改的过程中冒出的"顺手"冲动——顺手优化一下、顺手重构一点、顺手加个抽象。每一项单独看都说得通，但合在一个 PR 里就让别人分不清"这次到底为了修 bug 改了什么"。下面所有规则的目的都是让这种冲动停下来。

共享路径与命名约定看
codestable/reference/shared-conventions.md
第 0 节和
cs-issue
的"文件放哪儿"节。

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

标准路径入口（有 {slug}-analysis.md）

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

根因分析存在且方案已确认——读
```
{slug}-analysis.md
```
，确认 frontmatter 有
```
doc_type=issue-analysis
```
且
```
status=confirmed
```
，第 5 节"修复方案"用户选定了哪个方案
把上下文读全：
- 根因分析全文
- 问题报告全文
- 根因分析第 1 节定位到的所有代码文件
- ```
AGENTS.md
```
- 沉淀目录里与本 issue 相关的记录（统一搜
```
codestable/compound/
```
  ，按需用
```
doc_type
```
  过滤）：
  - 查技巧：
```
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter status=active --query "{issue 关键词}"
```
    ——确认修复方式不违背已有库用法 / 模式建议
  - 查探索：
```
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=explore --query "{issue 关键词}"
```
    ——确认修复点与已有证据不冲突
确认修复起点——告诉用户"我将按方案 X 修改 {文件列表}，开始修复"，等用户确认才动手

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

快速通道入口（无 {slug}-analysis.md，从 cs-issue-report 直接触发）

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

进入这个入口时，AI 在 report 阶段已经读过代码并对根因有把握。

向用户明确陈述根因："
```
{文件}:{行号}
```
的 {具体代码} 存在 {问题描述}"，让用户确认根因判断准确
给出修复方案——改哪里、怎么改（一两句话即可，不写成完整分析文档）
等用户明确说"对，就这样改"后才动手——不允许"我觉得对，直接改了"
读
```
AGENTS.md
```
补搜沉淀目录——快速通道也要用
```
search-yaml.py --dir codestable/compound
```
查一遍，
```
--filter doc_type=trick
```
看同类技巧，
```
--filter doc_type=explore
```
避免误把已知边界条件当成新问题

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

修复范围来自

{slug}-analysis.md

第 5 节"推荐方案"里的"影响面"。超出范围的文件——哪怕顺眼——不动。

发现范围外值得改的地方就记一条"顺手发现"，不改代码：

markdown

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

为什么这么严？理由跟 feature-implement 一样——顺手改的代码不在分析里，验收时核对不上，后人 git blame 也分不清哪些改动是为了修这个 bug。

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

修复的改动应该只针对根因，不引入新的抽象、新的接口、新的模式。如果发现"要把这个改好得先重构 X"——停下来，跟用户确认是否要在这个 issue 里做重构，还是拆成独立的工作。

为什么这么严？bug 修复天然是窄场景的动作。引入新抽象意味着这个抽象只有这一个使用点支撑——典型的过早抽象。要么先单独重构再修 bug，要么修完 bug 再单独重构，但别在一个 PR 里同时做。

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

修 bug 看似动作小，但 AI 写修复代码时一样会漂——在已经很长的文件里再塞一段特殊处理、在已经很重的类里再加一个方法、为了绕开某种边界情况加一个

if

分支。反射检查见

codestable/reference/shared-conventions.md

第 7 节。

issue-fix 下这一节要比 feature-implement 更谨慎：触发了反射信号但结论是"该拆"时，默认不在本次 PR 里做——按"改动最小化"的逻辑记成顺手发现，另开工作收拾。唯一例外是"不拆就没法干净地修这个 bug"，那就停下来跟用户明确"修这个 bug 的前置是 {重构动作}，要不要合进来还是拆出去单独做"。

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

修复汇报模板见同目录

reference.md

，不允许含糊汇报。汇报完后停下来等用户回复。

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

修复代码改完后，在汇报里逐项核对：

复现步骤验证：按
```
{slug}-report.md
```
第 2 节的步骤走一遍，问题不再出现
期望行为验证：
```
{slug}-report.md
```
第 3 节描述的"期望行为"现在确实发生
影响面回归：
```
{slug}-analysis.md
```
第 4 节"潜在受害模块"——每个模块走一遍最基本的冒烟路径，确认没被修复引入新问题
前端改动浏览器验证（如果涉及）：AGENTS.md 硬要求，不能只靠 typecheck
相关测试通过：如果有测试覆盖到修复区域，跑一遍

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

走完验证清单后如果发现问题仍然复现或行为与期望不符，别在原有猜测上反复试错——切换到日志调试模式，重新收集运行时证据。

为什么要切换？反复试错的本质是猜测在原假设下还有什么可能性，但如果原假设本身就错了，再多猜也是绕圈。日志会强制你看实际运行时数据，往往一眼就看出原假设哪里偏了。

日志调试步骤、用户取日志提示词和循环限制见同目录

reference.md

。

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.

写 {slug}-fix-note.md

Write {slug}-fix-note.md

验证通过后在 issue 目录下建

{slug}-fix-note.md

（位置见

cs-issue

的"文件放哪儿"节），记录本次修复的完整闭环。标准路径模板和快速通道模板都在同目录

reference.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

所有改动文件已提交或列清单
验证清单全部勾选
```
{slug}-fix-note.md
```
已建并填写完整（标准路径用标准模板，快速通道用快速通道模板）
没有未处理的"顺手发现"（都进了后续 issue 列表）
没有范围外的改动（或已和用户确认）
用户明确确认修复完成

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

按

codestable/reference/shared-conventions.md

第 4 节"收尾提交（scoped-commit）"的规则执行。本阶段的特定要点：

提交范围：修复代码、
```
{slug}-fix-note.md
```
，以及本次确实一并更新的
```
{slug}-report.md
```
/
```
{slug}-analysis.md
```
修复闭环后告诉用户"修复验证已完成，
```
{slug}-fix-note.md
```
已落盘"，紧接着问是否需要 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

告诉用户："issue 修复完成，工作流闭环。问题报告（{slug}-report.md）+ 根因分析（{slug}-analysis.md）+ 修复记录（{slug}-fix-note.md）已存档。"

然后按

codestable/reference/shared-conventions.md

第 3 节"issue-fix"收尾推荐顺序各问一句话（用户说"不用"立刻跳过）：

这次修复暴露了值得复用的坑点 / 经验 → "需要把这个坑沉淀成 learning 文档吗？（走
```
cs-learn
```
，会写入
```
codestable/compound/
```
）"
这次修复沉淀出了长期约束、规约或技术决定 → "需要把这条决定归档吗？（走
```
cs-decide
```
）"
最后补问一次是否需要代为提交本次修复。用户同意时按收尾提交规则执行到 commit 完成。

可以建议：

把 issue 目录下的文件和代码改动放在同一次提交里，方便日后追溯
"顺手发现"的后续 issue 另开一轮
```
cs-issue-report
```
处理，别在这个 PR 里塞

如果修复过程中发现问题实际上是功能缺失（不是 bug），建议用户另开

cs-feat

工作流处理，别在 issue 工作流里偷偷做新功能。

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

修完代码没走验证清单就宣告"修好了"
顺手改了根因分析范围外的代码
修复引入了新的抽象 / 接口但没停下来跟用户确认
```
{slug}-fix-note.md
```
没建就宣告工作流完成
发现影响面回归有问题但在汇报里写"轻微影响，可以忽略"——要修到干净
前端有改动但没在浏览器跑，只 typecheck 就报通过
用户没明确说"修复完成"就结束工作流
修复未生效但继续在原假设上反复猜测试错，不切换到日志调试
日志调试结束后没清理临时 log 语句就提交代码
工作流收尾时没问用户是否需要代为 commit
用户没明确同意就直接
```
git commit
```

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