cs-issue-fix

根因和方案已经确定（标准路径在 analysis、快速通道在 report 阶段口头确认过），你的活是按方案改代码、验证效果、写下修复记录。

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

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

两种入口

方案已确认——读 analysis，确认 doc_type=issue-analysis 且 status=confirmed，第 5 节用户选定了哪个方案
上下文读全：analysis 全文 + report 全文 + analysis 第 1 节定位的所有代码 + AGENTS.md + 沉淀目录搜索：
- python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter status=active --query "{关键词}"——确认修复方式不违背已有库用法 / 模式
- 同样命令换 --filter doc_type=explore——确认修复点和已有证据不冲突
确认起点——告诉用户"我将按方案 X 修改 {文件列表}，开始修复"，等用户确认才动手

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

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

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

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

为什么这么严：顺手改的代码不在分析里，验收对不上，git blame 分不清哪些改动是为这个 bug。

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

为什么：bug 修复天然窄场景，引入新抽象意味着只有这一个使用点支撑——典型过早抽象。

修 bug 看似动作小但 AI 写修复代码一样会漂——大文件再塞特殊处理、大类再加方法、为绕开边界加 if 分支。反射检查见 shared-conventions.md 第 7 节。

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

修复汇报模板见同目录 reference.md，不允许含糊汇报。汇报后停下等用户回复。

修复改完后逐项核对：

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

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

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

验证通过后在 issue 目录建 {slug}-fix-note.md（位置见 cs-issue 的"文件放哪儿"），记录完整闭环。标准路径模板和快速通道模板都在同目录 reference.md。

按 shared-conventions.md 第 4 节"scoped-commit"规则执行。本阶段：

告诉用户："issue 修复完成，工作流闭环。report + analysis + fix-note 已存档。"

按 shared-conventions.md 第 3 节"issue-fix"收尾推荐顺序各问一句（用户"不用"立即跳过）：

暴露了值得复用的坑点 → "沉淀 learning？（cs-learn）"
沉淀出长期约束 / 规约 / 技术决定 → "归档决定？（cs-decide）"
这个 bug 暴露了项目通用的硬约束 / 命令陷阱 / 环境设置（一两行能讲清、AI 每次会话都该知道）→ "记到 AGENTS.md？（cs-note）"
最后问是否代为提交。同意时按收尾提交规则执行

建议：把 issue 目录文件和代码改动放同一次提交方便追溯；"顺手发现"另开 cs-issue-report 处理别塞这个 PR。

修复中发现问题实际是功能缺失（不是 bug）→ 建议另开 cs-feat，别在 issue 工作流里偷偷做新功能。