bug-fixer

name	bug-fixer
description	系统化调试修复 Bug。五阶段：收集证据→重现用例→分析(含根因归因)→假设→修复→进化记录。支持触发 code-review 和 feedback-writer。

Bug Fixer — Bug 修复

职责

系统化地调试和修复 Bug。核心原则是 先调查根本原因，再尝试修复。禁止在看到报错后立即猜测性修改。

触发场景

• 用户报告 Bug 或异常行为
• 测试失败
• 构建失败
• 性能问题

铁律

不找出根本原因就不允许修复

如果还没完成阶段 1（证据收集），就不能进入阶段 4（修复）。

四阶段工作流程

阶段 1：收集证据

1. 仔细阅读错误信息

   • 不要跳过任何 error 或 warning
   • 阅读完整的堆栈跟踪
   • 记录行号、文件路径、错误码

2. 稳定复现

   • 能否稳定触发？
   • 精确的复现步骤是什么？
   • 每次都发生还是偶发？

3. 检查最近的变更

   • git diff 和最近的 commits
   • 新依赖、配置变更
   • 环境差异

4. 收集完整上下文

   • 输入输出数据
   • 环境信息（OS、版本等）
   • 日志文件

阶段 1.5：编写重现用例

将证据转化为可重现的测试或复现脚本。

1. 基于阶段 1 收集的复现步骤，编写最小重现用例
2. 确认用例在当前代码上确实失败（证明 bug 存在）
3. 这是后续"修复有效"的客观验证标准——用例通过 = bug 修好了

阶段 2：分析规律

• 找出错误模式
• 确定边界条件
• 识别技术原因类别（逻辑错误/边界条件/竞态/类型错误/配置问题等）
• 确定根因归因类型（必须四选一）：

根因类型	定义	举例
需求遗漏	PRD/验收标准没写清楚，导致理解偏差	"没说空状态要怎么展示"
设计遗漏	设计规范/ADR 未覆盖该场景	"设计稿没有错误态的样式"
编码失误	需求设计都明确，实现写错了	"循环里漏了 break"
边界遗漏	正常路径对但极端输入/并发/超时未处理	"文件超过 1GB 时 OOM"

阶段 3：提出假设

• 基于证据提出修复假设
• 验证假设（通过日志、小测试等方式）
• 排除不正确的假设
• 确定最终的修复方案

阶段 4：实施修复

• 实施最小必要的修复
• 运行阶段 1.5 的重现用例，确认通过（Bug 不再复现）
• 确认没有引入回归问题（运行现有测试套件）
• 提交修复并附上说明

阶段 4.5：根因归因与进化记录

1. 写入文档错误记录表

将 Bug 追加到对应文档的「决策与错误记录 > 错误与修复」表：

| 错误 | 影响 | 根因类型 | 修复方式 | 日期 |
|------|------|---------|---------|------|
| <Bug 描述> | <影响范围> | 需求遗漏/设计遗漏/编码失误/边界遗漏 | <修复摘要> | YYYY-MM-DD |

• 根因类型为需求遗漏 → 写入 Product-Spec.md
• 根因类型为设计遗漏 → 写入 Design-Brief.md
• 根因类型为编码失误或边界遗漏 → 写入 Dev-Plan.md

2. 触发进化反馈

如果根因类型是编码失误或设计遗漏，调用 feedback-writer，记录结构化反馈：

feedback 内容：
  - type: "correction"
  - skill: 受影响的 skill（product-spec-builder / design-brief-builder / implementer 等）
  - context: "Bug 修复中发现：<根因类型>"
  - issue: "<具体问题描述>"
  - resolution: "<修复方式>"

这样进化引擎才能在后续扫描到同一模式出现 ≥3 次时，触发对应 Skill 的优化提案。

3. 判断是否需要 code-review

修复完成后，判断以下条件：

• 修复涉及代码改动 > 20 行 → 触发 code-review
• 修复涉及接口/类型/数据模型变更 → 触发 code-review
• 否则 → 跳过 code-review，直接记录

阶段 5：更新进度

更新 .claude/progress.json：

• milestones 追加「Bug 修复：<摘要>（根因：<类型>）」

输出

• Bug 分析报告（技术原因 + 根因归因 + 修复方案）
• 修复后的代码 + 验证结果
• 对应文档「决策与错误记录」表追加记录（含根因类型）
• 根因为编码失误/设计遗漏时，触发 feedback-writer
• 改动 >20 行或涉及接口变更时，触发 code-review

参考资源

• systematic-debugging — 系统化调试方法论（本技能基于此）