systematic-debugging

name	systematic-debugging
description	系统化调试 SOP，通过复现→根因→影响面→修复→回归的五步流程，避免盲目修 Bug 引入新问题
when_to_use	用于 Bug 调试、根因分析、复现验证、影响面评估、回归避免时调用。 典型触发："修这个 bug" / "为什么会出错" / "复现 X" / "根因是什么" / "影响面"。 不用于：技术方案设计（用 technical-design）/ 代码审查（用 code-review）/ 测试用例设计（用 test-case-design）。
user-invocable	true
allowed-tools	["Read","Write","Edit","Glob","Grep","Bash"]

系统化调试技能

产物去向

RCA / 调试结论默认只在响应中呈现。需要留痕时：修复本身进 commit message； 值得跨需求复用的根因结论按 skill: document-norms §1 落 <sub>/decisions/； 线上故障走 projects/issues/BUG-*.yaml。不默认写文件。

适用场景

• @dev 收到 Bug/Issue 报告时（来自 @qa、用户反馈、线上监控等）
• 禁止"头痛医头脚痛医脚"式的随意修改

核心原则

先理解，再修复。修复前必须能回答三个问题：

1. 为什么会出现这个 Bug？（根因）
2. 这个修复会不会引入新 Bug？（影响面）
3. 修复后如何验证确实修好了？（回归）

五步流程

第 1 步：复现确认

目标：确认问题存在且能稳定复现。

步骤	动作
读取 Issue	从 projects/issues/{issue-id}.yaml 读取问题描述、复现步骤（issue-id 是全局唯一扁平 ID，例：BUG-001 / SEC-001；issues 目录是扁平结构，不按模块分子目录）
解析归属	读取 Issue 的 area / module / component / spec_ref 字段，决定影响面分析的起点（例：area=backend, module=auth 提示先排查 auth 模块代码与相关 spec）
构造复现条件	按 Issue 描述构造输入数据、执行环境、操作序列
执行复现	运行并观察实际输出 vs 期望输出
复现结论	✅ 能稳定复现 / ⚠️ 偶发 / ❌ 无法复现

如果无法复现：

• 向 Issue 报告者询问更详细的复现步骤
• 检查环境差异（版本、配置、数据）
• 不要立即关闭 Issue——保持 status: open，把「待补充的复现信息」写进 issue 的复现步骤/描述字段（issue schema 无 tags 字段，见 projects/issues/TEMPLATES.md）

第 2 步：根因分析（RCA）

目标：定位问题代码并理解"为什么会出错"。

## 根因分析

### 症状
{Bug 的外在表现}

### 触发路径
{代码执行的调用链：A → B → C → 出错}

### 根因
{具体哪行代码、哪个逻辑导致问题}

### 为什么会写成这样
{原作者的意图 / 遗漏的边界条件 / 错误的假设}

### 为什么之前没暴露
{之前的使用场景为何没触发此问题}

第 3 步：影响面评估

目标：评估修复可能波及的其他模块（Blast Radius）。

评估维度	说明
代码依赖	谁调用了这段出错代码？改动后他们会受影响吗？
数据影响	修复会改变数据结构/存储吗？老数据需要迁移吗？
接口变更	是否改变了对外 API 行为？调用方需要知晓吗？
性能影响	修复引入的新逻辑是否影响性能？
安全影响	修复是否引入新的安全隐患？

第 4 步：修复与自测

目标：执行修复并验证修复有效。

1. 实施修复：最小范围修改，不做无关重构
2. 复现步骤重跑：确认原问题不再出现
3. 边界测试：测试修复逻辑的边界条件（空值、极值、并发等）
4. 影响面验证：对 Step 3 识别的影响模块做快速验证

第 5 步：回归标注

目标：为 @qa 标注此次修复的回归测试要点。

## 回归测试要点

### 必测（直接相关）
- [ ] 原 Bug 复现场景已修复
- [ ] 修复代码的边界条件测试

### 建议测（影响面）
- [ ] {被影响的模块 A}
- [ ] {被影响的模块 B}

### 关注点（潜在风险）
- {需要长期观察的性能/稳定性指标}

输出模板

## RCA 报告：{Issue-ID}

### 1. 复现确认
- 复现结果：{✅ 稳定复现 / ⚠️ 偶发 / ❌ 无法复现}
- 复现步骤：{...}

### 2. 根因分析
- 症状：{...}
- 触发路径：{...}
- 根因：{具体代码位置 + 错误逻辑}
- 为什么会写成这样：{...}

### 3. 影响面评估
- 代码依赖：{...}
- 数据影响：{...}
- 接口变更：{...}

### 4. 修复方案
- 修改文件：{路径}
- 修改内容：{具体改动}
- 自测结果：{...}

### 5. 回归测试要点
- 必测：{...}
- 建议测：{...}

下游衔接

• board.yaml：Bug 修复任务完成后，状态改为 pending_qa
• @qa test-case-design：基于回归测试要点设计测试用例
• technical-design：如果修复需要改动架构，走技术方案设计流程

反模式

• ❌ 看到报错就改代码，不分析根因
• ❌ 只看修复后"能跑了"，不测边界条件
• ❌ 修复后不标注回归要点，QA 盲测
• ❌ 修复时顺手重构无关代码，扩大变更范围
• ❌ "这个问题之前就有"就不修了