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
当你有一份书面实现计划需要在单独的会话中执行，并设有审查检查点时使用
在开始任何对话时使用——确立如何查找和使用技能，要求在任何响应（包括澄清性问题）之前调用 Skill 工具
在任何创造性工作之前必须使用此技能——创建功能、构建组件、添加功能或修改行为。在实现之前先探索用户意图、需求和设计。
当实现完成、所有测试通过、需要决定如何集成工作时使用——通过提供合并、PR 或清理等结构化选项来引导开发工作的收尾
当需要开始与当前工作区隔离的功能开发，或在执行实现计划之前使用——通过原生工具或 git worktree 回退机制确保隔离工作区存在
中文 review 沟通参考——话术模板、分级标注（必须修复/建议修改/仅供参考）、国内团队常见反模式应对。仅在用户显式 /chinese-code-review 时调用，不要根据上下文自动触发。
| name | systematic-debugging |
| description | 遇到任何 bug、测试失败或异常行为时使用，在提出修复方案之前执行 |
| version | 1.0.0 |
| license | MIT |
| metadata | {"hermes":{"tags":["debugging"]}} |
随意修复既浪费时间又会引入新 bug。草率的补丁只会掩盖深层问题。
核心原则： 在尝试修复之前，务必先找到根本原因。只修症状就是失败。
敷衍走流程等于违背调试的精神。
不做根因调查，不许提修复方案
如果你还没完成第一阶段，就不能提出修复方案。
用于任何技术问题：
尤其在以下情况必须使用：
以下情况也不要跳过：
你必须完成每个阶段后才能进入下一个。
在尝试任何修复之前：
仔细阅读错误信息
稳定复现
检查近期变更
在多组件系统中收集证据
当系统有多个组件时（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 技能来编写规范的失败测试实施单一修复
验证修复
如果修复不起作用
如果 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 - 用条件轮询替代硬编码等待时间相关技能：
调试实践中的数据：