Menú
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
Before any creative work — creating features, building components, adding capabilities, or modifying behavior — you must use this skill. Explore user intent, requirements, and design before implementation.
Use when executing implementation plans with independent tasks in the current session
Use when implementing any feature or bug fix, before writing implementation code
Use when creating new skills, editing existing skills, or verifying skills work before deployment
Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
Use when you have a written implementation plan to execute in a separate session with review checkpoints
| name | systematic-debugging |
| description | Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes |
随机修复浪费时间并制造新 bug。快速补丁掩盖了潜在问题。
核心原则： 在尝试任何修复之前，始终找到根本原因。修复症状是失败。
违反这条规则的文字就是违反调试的精神。
未经根本原因调查，不得修复
如果你没有完成第一阶段，你就不能提出修复方案。
适用于任何技术问题：
特别要在以下情况使用：
不要跳过当：
你必须完成每个阶段后才能进入下一个。
在任何修复之前：
仔细阅读错误消息
稳定复现
检查最近的更改
在多组件系统中收集证据
当系统有多个组件时（CI → 构建 → 签名、API → 服务 → 数据库）：
在提出修复之前，添加诊断工具：
对于每个组件边界：
- 记录进入组件的数据
- 记录离开组件的数据
- 验证环境/配置传播
- 检查每层的状态
运行一次以收集证据，显示它在哪里断裂
然后分析证据以识别故障组件
然后调查那个特定组件
示例（多层系统）：
# 第 1 层：工作流
echo "=== 工作流中可用的密钥：==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
# 第 2 层：构建脚本
echo "=== 构建脚本中的环境变量：==="
env | grep IDENTITY || echo "IDENTITY not in environment"
# 第 3 层：签名脚本
echo "=== 钥匙串状态：==="
security list-keychains
security find-identity -v
# 第 4 层：实际签名
codesign --sign "$IDENTITY" --verbose=4 "$APP"
这揭示了： 哪一层失败（密钥 → 工作流 ✓，工作流 → 构建 ✗）
追踪数据流
当错误在调用栈深处时：
参见本目录中的 root-cause-tracing.md，了解完整的向后追踪技术。
快速版本：
修复前先找模式：
找到工作的示例
与参考对比
识别差异
理解依赖
科学方法：
形成单一假设
最小化测试
继续前验证
当你不知道时
修复根本原因，而非症状：
创建失败的测试用例
superpowers:test-driven-development 技能来编写正确的失败测试实施单一修复
验证修复
如果修复不起作用
如果 3+ 次修复失败：质疑架构
表明架构问题的模式：
停止并质疑基本原则：
在尝试更多修复之前与你的伙伴讨论
这不是失败的假设 —— 这是错误的架构。
如果你发现自己有以下想法：
所有这些意味着：停止。回到第一阶段。
如果 3+ 次修复失败： 质疑架构（见第四阶段 5）
注意这些重新定向：
当你看到这些时： 停止。回到第一阶段。
| 借口 | 现实 |
|---|---|
| "问题很简单，不需要流程" | 简单问题也有根本原因。流程对简单 bug 也很快。 |
| "紧急，没时间走流程" | 系统性调试比猜测-检查式折腾更快。 |
| "先试试这个，然后再调查" | 第一次修复就设定了模式。从一开始就用正确的方法。 |
| "确认修复有效后再写测试" | 未测试的修复不持久。先测试才能证明它有效。 |
| "一次多修复节省时间" | 无法隔离什么起作用了。会导致新 bug。 |
| "参考资料太长了，我会调整模式" | 部分理解保证有 bug。完整阅读它。 |
| "我看到问题了，让我修复它" | 看到症状 ≠ 理解根本原因。 |
| "再试一次修复"（2+ 次后） | 3+ 次失败 = 架构问题。质疑模式，不要再次修复。 |
| 阶段 | 关键活动 | 成功标准 |
|---|---|---|
| 1. 根本原因 | 读错误、复现、检查更改、收集证据 | 理解 WHAT 和 WHY |
| 2. 模式 | 找工作的示例、对比 | 识别差异 |
| 3. 假设 | 形成理论、最小化测试 | 已确认或新假设 |
| 4. 实施 | 创建测试、修复、验证 | Bug 解决，测试通过 |
如果系统性调查表明问题确实是环境的、时间依赖的或外部的：
但是： 95% 的"无根本原因"案例是调查不完整。
这些技术是系统性调试的一部分，在本目录中可用：
root-cause-tracing.md —— 通过调用栈向后追踪 bug 以找到原始触发点defense-in-depth.md —— 在找到根本原因后在多层添加验证condition-based-waiting.md —— 用条件轮询替换任意超时相关技能：
来自调试会话：