Menu
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
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.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/jnMetaCode/superpowers-zh --skill systematic-debuggingThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Based on SOC occupation classification
Showing SKILL.md
| name | systematic-debugging |
| description | 遇到任何 bug、测试失败或异常行为时使用，在提出修复方案之前执行 |
| version | 1.0.0 |
| license | MIT |
| metadata | {"hermes":{"tags":["debugging"]}} |
核心原则： 在尝试修复之前，务必先找到根本原因。只修症状就是失败。
敷衍走流程等于违背调试的精神。
不做根因调查，不许提修复方案
如果你还没完成第一阶段，就不能提出修复方案。
用于任何技术问题：
尤其在以下情况必须使用：
以下情况也不要跳过：
你必须完成每个阶段后才能进入下一个。
在尝试任何修复之前：
仔细阅读错误信息
稳定复现
检查近期变更
在多组件系统中收集证据
当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：
在提出修复方案之前，先添加诊断埋点：
对每个组件边界：
- 记录进入组件的数据
- 记录离开组件的数据
- 验证环境/配置的传递
- 检查每一层的状态
执行一次以收集证据，确定断裂点在哪里
然后分析证据，定位故障组件
然后针对该组件深入调查
示例（多层系统）：
# 第 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 技能来编写规范的失败测试实施单一修复
验证修复
superpowers:verification-before-completion 技能如果修复不起作用
如果 3 次以上修复都失败了：质疑架构
以下模式表明存在架构问题：
停下来质疑根本性问题：
在尝试更多修复之前，和你的搭档讨论
这不是假设失败——这是架构有误。
如果你发现自己在想：
以上这些都意味着：停下来。回到第一阶段。
如果 3 次以上修复都失败了： 质疑架构（见第四阶段第 5 步）
留意这些提醒：
当你看到这些信号时： 停下来。回到第一阶段。
| 借口 | 现实 |
|---|---|
| "问题很简单，不需要走流程" | 简单问题也有根本原因。对于简单 bug，流程很快就能走完。 |
| "紧急情况，没时间走流程" | 系统化调试比反复猜测式修复更快。 |
| "先试一下，再排查" | 第一次修复就定下了基调。从一开始就做对。 |
| "确认修复有效后再写测试" | 没有测试的修复留不住。先写测试才能证明修复有效。 |
| "一次修多个问题省时间" | 无法隔离哪个生效了。还会引入新 bug。 |
| "参考实现太长了，我自己改改" | 一知半解必然出 bug。完整阅读。 |
| "我看出问题了，让我修一下" | 看到症状 ≠ 理解根因。 |
| "再试一次"（在 2 次以上失败后） | 3 次以上失败 = 架构问题。质疑模式，不要继续修。 |
| 阶段 | 关键活动 | 通过标准 |
|---|---|---|
| 1. 根因 | 阅读错误、复现、检查变更、收集证据 | 理解了什么出了问题以及为什么 |
| 2. 模式 | 找到正常示例、对比 | 识别出差异 |
| 3. 假设 | 提出理论、最小化验证 | 假设被验证或产生新假设 |
| 4. 实施 | 创建测试、修复、验证 | bug 已修复，测试通过 |
如果系统化排查后发现问题确实是环境相关、时序相关或外部因素导致的：
但是： 95% 的"找不到根因"其实是排查不充分。
以下技术是系统化调试的组成部分，可在本目录中找到：
root-cause-tracing.md - 沿调用栈反向追踪 bug，找到最初的触发点defense-in-depth.md - 找到根因后，在多个层级添加校验condition-based-waiting.md - 用条件轮询替代硬编码等待时间