---
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 · 全局验证（七问之 7）

- 重新运行用户最初描述失败的场景，确认问题消失。
- 运行相关测试套件，确认没有引入新问题。
- 在最终回复里附上验证证据（命令输出、`file:line` 引用）。

## 禁止行为

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

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

## 输出契约

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

1. **根源说明**（一段话讲清楚机理）
2. **修改清单**（含 `file:line`）
3. **连带项处理**（"我同时改了 X / 检查了 Y / 未改 Z 因为…"）
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)。