Menu
当遇到任何 bug、测试失败或意外行为时使用，在提出修复方案之前
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | systematic-debugging |
| description | 当遇到任何 bug、测试失败或意外行为时使用，在提出修复方案之前 |
随机修复浪费时间并制造新的 bug。快速的补丁掩盖了底层问题。
核心原则： 在尝试任何修复之前，必须找到根因。只修症状就是失败。
违反此流程的字面意义，就是违反调试的精神。
没有先进行根因调查，就不做任何修复
如果你没有完成阶段 1，你不能提出修复方案。
用于任何技术问题：
尤其在这些情况下使用：
不要在这些情况下跳过：
你必须完成每个阶段才能进入下一个。
在尝试任何修复之前：
仔细阅读错误信息
稳定复现
检查最近变更
在多组件系统中收集证据
当系统有多个组件时（CI → build → signing，API → service → database）：
在提出修复之前，添加诊断插桩：
对每个组件边界：
- 记录进入组件的数据
- 记录离开组件的数据
- 验证环境/配置的传递
- 检查每一层的状态
运行一次以收集证据，显示它在哪里中断
然后分析证据以识别失败的组件
然后调查那个具体组件
示例（多层系统）：
# 第 1 层：工作流
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
# 第 2 层：构建脚本
echo "=== Env vars in build script: ==="
env | grep IDENTITY || echo "IDENTITY not in environment"
# 第 3 层：签名脚本
echo "=== Keychain state: ==="
security list-keychains
security find-identity -v
# 第 4 层：实际签名
codesign --sign "$IDENTITY" --verbose=4 "$APP"
这揭示： 哪一层失败（secrets → workflow ✓，workflow → build ✗）
追踪数据流
当错误深在调用栈中时：
参见本目录下的 root-cause-tracing.md，了解完整的反向追踪技术。
快速版本：
在修复之前先找到模式：
找到可用的示例
与参考对比
识别差异
理解依赖
科学方法：
形成单一假设
最小化测试
在继续之前验证
当你不知道时
修复根因，而不是症状：
创建失败的测试用例
superpowers:test-driven-development skill 来编写规范的失败测试实现单一修复
验证修复
如果修复没生效
如果 3 次以上修复失败：质疑架构
指示架构问题的模式：
停下并质疑根本：
在尝试更多修复之前与你的 human partner 讨论
这不是失败的假设——这是错误的架构。
如果你发现自己在想：
以上全部意味着：停下。回到阶段 1。
如果 3 次以上修复失败： 质疑架构（见阶段 4.5）
注意这些纠正：
当你看到这些时： 停下。回到阶段 1。
| 借口 | 现实 |
|---|---|
| "问题很简单，不需要流程" | 简单问题也有根因。流程对简单 bug 很快。 |
| "紧急情况，没时间走流程" | 系统化调试比猜-检查-瞎折腾更快。 |
| "先试这个，再调查" | 第一次修复设定了模式。从一开始就做对。 |
| "我先确认修复有效，再写测试" | 未测试的修复留不住。测试先行才能证明它。 |
| "一次多个修复节省时间" | 无法隔离哪个生效。制造新的 bug。 |
| "参考太长了，我适配一下模式" | 部分理解必然导致 bug。完整地阅读它。 |
| "我看到问题了，让我修一下" | 看到症状 ≠ 理解根因。 |
| "再试一次修复"（失败 2 次以上后） | 3 次以上失败 = 架构问题。质疑模式，不要再修。 |
| 阶段 | 关键活动 | 成功标准 |
|---|---|---|
| 1. 根因 | 阅读错误、复现、检查变更、收集证据 | 理解是什么和为什么 |
| 2. 模式 | 找到可用示例、对比 | 识别差异 |
| 3. 假设 | 形成理论、最小化测试 | 假设确认或新假设 |
| 4. 实现 | 创建测试、修复、验证 | Bug 解决、测试通过 |
如果系统化调查揭示问题确实是环境性的、时序相关的或外部的：
但是： 95% 的"没有根因"案例都是不完整的调查。
这些技术是系统化调试的一部分，可在本目录中找到：
root-cause-tracing.md - 通过调用栈反向追踪 bug，找到原始触发点defense-in-depth.md - 在找到根因后在多个层添加校验condition-based-waiting.md - 用条件轮询替代随意超时相关 skills：
来自调试会话：
在进行任何创造性工作之前，你必须使用此 skill - 创建功能、构建组件、添加功能或修改行为。在实现之前探索用户意图、需求和设计。
当面对 2 个以上可在无共享状态或顺序依赖下处理的独立任务时使用
当你有一个书面实现计划，需要在带有 review 检查点的独立会话中执行时使用
当实现完成、所有测试通过、且你需要决定如何集成工作时使用 - 通过为合并、PR 或清理呈现结构化选项来指导开发工作的完成
当收到代码审查反馈时使用，在实现建议之前，尤其是当反馈看似不清或在技术上存疑时 - 需要技术严谨性和验证，而非表演性附和或盲目实现
当完成任务、实现主要功能或合并之前使用，以验证工作满足需求