easysdd-issue-fix

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

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

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

两种入口

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

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

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

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

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

实现期间的约束

只改根因分析里声明的文件

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

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

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

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

改动最小化

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

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

代码质量反射检查

修 bug 看似动作小，但 AI 写修复代码时一样会漂——在已经很长的文件里再塞一段特殊处理、在已经很重的类里再加一个方法、为了绕开某种边界情况加一个 if 分支。反射检查见 easysdd/reference/shared-conventions.md 第 7 节。

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

每完成一处改动必须汇报

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

验证清单

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

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

修复未生效时：日志调试升级

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

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

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

写 {slug}-fix-note.md

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

退出条件

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

收尾提交

按 easysdd/reference/shared-conventions.md 第 4 节"收尾提交（scoped-commit）"的规则执行。本阶段的特定要点：

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

退出后

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

然后按 easysdd/reference/shared-conventions.md 第 3 节"issue-fix"收尾推荐顺序各问一句话（用户说"不用"立刻跳过）：

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

可以建议：

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

如果修复过程中发现问题实际上是功能缺失（不是 bug），建议用户另开 easysdd-feature 工作流处理，别在 issue 工作流里偷偷做新功能。

容易踩的坑

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