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）

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

```markdown
## 根因分析

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

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

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

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

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

### 第 3 步：影响面评估

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

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

### 第 4 步：修复与自测

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

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

### 第 5 步：回归标注

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

```markdown
## 回归测试要点

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

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

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

## 输出模板

```markdown
## RCA 报告：{Issue-ID}

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

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

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

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

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

## 下游衔接

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

## 反模式

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