Systematic Debugging

---
name: systematic-debugging
description: '系统化调试 SOP，通过复现→根因→影响面→修复→回归的五步流程，避免盲目修 Bug 引入新问题。用于 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 标注此次修复的回归测试要点**。

> **三个桶按什么分**：广度来自**同族边界三问**——这个事实还有几份副本？这个约定还有几个使用方？周边还有哪些同类条目没碰到？答得出的进「必测」，搜到但没把握的进「建议测」，只是同族、本次没碰的进「关注点」。
>
> 与本 skill 第 3 步影响面五维**互补不重合**：五维按技术维度切、产出影响清单；三问按「同一事实的多处存在」切、产出测试范围。**两组都要过。**
>
> **标到多深，先定档**（三问全部问完，命中取最高档；答「是」或「说不准」都算命中）：① 错了会不会传出这个文件之外 → 至少**档 2**　② 有没有东西会因**你改的那部分内容**产出可比较的结果（通过/不通过、分数、diff、快照）→ 至少**档 3**　③ 改的对象本身的职责就是「判断别的东西对不对」吗 → **档 4**；全不命中 → **档 1**。档 1 只验主路径与一致性，每升一档累加：引用面核对 → 跑真实消费方并排对照 + 边界矩阵 → 用它自己的失败方式打一遍（档 4 广度还要加上「同契约的其他实现」）。
>
> 详表与反例在 `test-scoping.md`（能读到插件目录时：`"$(cat .workframe/state/plugin-root.txt)/skills/test-case-design/reference/test-scoping.md"`）；**读不到是常态，上面三问已够定档**。

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

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

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

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

## 输出模板

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

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

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

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

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

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

## 下游衔接

- **board.yaml**：Bug 修复任务完成后，状态改为 `pending_qa`。签发档由四段闸门判定（必载片 §谁签发这次收口），**自签档默认开启**（`signoff.self_signoff_enabled` 缺键即 true），降档要有覆盖本轮 delta 的通行证
- **返工轮的通行证有一个具体的坑**：被打回的 Bug 修复轮里，上一轮 @qa 的打回结论是最容易被当成通行证的东西——但**它覆盖的是被打回的那部分，没覆盖你这一轮新写的修复代码**。通行证问的是「有没有覆盖**本轮 delta**的独立结论」，而本轮 delta 恰恰是那份结论产生之后才存在的。**判据一句话：那份结论看没看过你这次改的这几行？** 没看过就不成立
- **@qa test-case-design**：基于回归测试要点设计测试用例
- **technical-design**：如果修复需要改动架构，走技术方案设计流程

## 反模式

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