---
name: systematic-debug
description: 在 debug / 修 bug / 异常排查 / "为什么不工作" 等语境下自动唤起。强制 agent 先走完根因分析的 7 问与 5 步骤，禁止直接给出反应式修补。当用户描述：bug、错误、stack trace、异常行为、"为什么 X 失败"、"为什么 Y 不工作"、"修一下这个"、"测试不过"、"500 报错"、"突然就坏了" 等情形时使用。
---

# systematic-debug — 系统式 debug 流程

> 你（主代理）已被本 skill 接管。在解决用户描述的问题前，**必须**按以下流程进行根因分析。
> 这个 skill 是 [`rules/02-systematic-not-reactive.md`](rules/02-systematic-not-reactive.md) 与 [`rules/03-root-cause.md`](rules/03-root-cause.md) 的强制执行入口。

## 强制流程（按顺序执行，不允许跳步）

### Step 1 · 复述与边界

用一两句话**复述**用户描述的问题，并明确：

- 什么是已知症状？（具体报错信息、行为差异、影响范围）
- 什么是**未知**？（哪些信息你目前没有，需要去看/去问）
- 什么**不是**这个问题？（明确排除范围以避免漫无目的探索）

⚠️ 如果用户给的信息不足以让你写出"已知/未知"清单，**先问用户**或**先读相关文件/日志**，不要立即开始修。

### Step 2 · 架构定位（七问之 1-2）

回答：

1. 这个问题出现的代码区域在**整个项目架构**中的哪个位置？
2. 那块代码的当前职责是什么？上游调用方是谁？下游被谁调用？

⚠️ 如果你尚未 `Read` 过涉事文件的完整内容，**现在就读**（规则 04）。

### Step 3 · 假设根源（七问之 3）

提出 **2-3 个可能的根源假设**（不要只想一个 → 容易锚定）。每个假设要：

- 描述机理（**为什么**这个原因会导致观察到的症状）
- 列出可证伪的预测（"如果是这个原因，那么我应该看到 X / 不应该看到 Y"）

### Step 4 · 验证假设（规则 01）

针对每个假设：

- 设计一个**可执行的验证步骤**：读哪个文件的哪几行 / 跑哪条命令 / 检查哪个 commit。
- 实际执行验证（用 `Read` / `Grep` / `Bash`）。
- 收集证据（粘贴 `file:line` 内容或命令输出）。
- 判定：confirmed / refuted / inconclusive。

⚠️ 不允许凭"看起来应该是 X"就跳到 Step 5。

### Step 5 · 确认根源 + 评估方案（七问之 4-5-6）

- 哪个假设被证据 confirmed？描述完整因果链：**根源 → 中间机理 → 观察到的症状**。
- 拟提出的修复方案：是否触达根源（不是 try/except、不是 sleep、不是 --no-verify）？
- 连带影响：哪些下游/测试/文档需要同步改？
- 风险：可能破坏哪些既有不变量？

### Step 6 · 实施修改

- 应用最小有效修改（规则 02.6）。
- 对每个连带项也同步修改。
- 修改时禁止规则 03 列出的反模式。

### Step 7 · 收敛验证（rule 06 强制）

> 这一步是 [`rules/06-verify-convergence.md`](rules/06-verify-convergence.md) 的执行入口。
> 完成下面所有子步骤前**禁止**声称完成；如有任意一步揭示问题未解决，**回到 Step 3 重新假设根源**。

**7.1 · 重触发原症状**：用用户在 Step 1 描述的同一条命令 / 输入重跑。粘贴新输出，明确"原报错消失"。

**7.2 · 边界 + 反向用例**：至少跑 1 个边界（空输入 / 错误路径 / 并发 / 跨平台 / Unicode）+ 1 个反向用例（应该 fail 的仍 fail）。

**7.3 · 连带不破坏**：跑相关测试套件 + lint + 类型检查；附输出。

**7.4 · 自答 4 题（必须显式回答）**：
1. **是不是真的解决了？** 证据是什么？如何排除"巧合 / 缓存 / 环境差异"？
2. **有没有更好的方案？** 与替代方案在简洁性 / 性能 / 可维护性 / 架构契合度上对比？
3. **改动是否经过验证？** 哪些没验？为什么不需要？
4. **验证是否合理？** 我跑的测试对应原问题的哪个机理？是否覆盖了 Step 5 中的根因因果链？

**7.5 · 量化（仅性能/竞态/兼容性修复）**：给数字 / 给重跑次数 / 给测试矩阵。

⚠️ 任意子步骤的答案是 "不知道 / 应该可以 / 差不多" → **未收敛，回 Step 3**。

## 禁止行为

直接跳到 Step 6 是本 skill 最常见的违规模式。具体禁止：

- ❌ 看到 stack trace 第一行就在那一行上加 try/except → 这是规则 03 反模式
- ❌ 测试失败就让测试通过（不问为什么之前失败）
- ❌ "我猜可能是 X" → 改 X → "应该好了" → 通通是反应式
- ❌ 跳过 Step 4（验证假设）直接进 Step 5

## 输出契约

完成上述流程后，最终回复给用户的内容**必须包含**：

1. **根源说明**（一段话讲清楚机理）
2. **修改清单**（含 `file:line`）
3. **连带项处理**（"我同时改了 X / 检查了 Y / 未改 Z 因为…"）
4. **收敛验证证据**（rule 06 的 Step 7 全部 5 个子步骤的产物：重触发输出、边界用例结果、连带测试结果、4 题自答、量化对比）

如果中途发现问题超出预期复杂度（例如根源在另一个模块），**先回到用户**说明情况，不要单方面扩大修改范围。

> 关联规则：[`rules/02-systematic-not-reactive.md`](rules/02-systematic-not-reactive.md)、[`rules/03-root-cause.md`](rules/03-root-cause.md)、[`rules/04-full-context.md`](rules/04-full-context.md)、[`rules/06-verify-convergence.md`](rules/06-verify-convergence.md)。