Menu
当遇到任何 bug、测试失败或意外行为时使用，在提出修复之前
在进行任何创造性工作之前，你必须使用此功能——创造特性、构建组件、添加功能或修改行为。在实施之前探索用户意图、需求和设计。
当面临 2 个以上可以独立工作且没有共享状态或顺序依赖关系的任务时使用
当你有一份书面的实施 plan 要在单独的会话中执行，并带有审查检查点时使用
当实施完成，所有测试通过，你需要决定如何集成工作时使用 - 通过提供合并、PR 或清理的结构化选项来指导开发工作的完成
当完成任务、实施主要功能或在合并之前验证工作是否符合要求时使用
当在当前会话中执行具有独立任务的实施 plans 时使用
| name | systematic-debugging |
| description | 当遇到任何 bug、测试失败或意外行为时使用，在提出修复之前 |
随意的修复浪费时间并产生新的 bugs。快速补丁会掩盖潜在问题。
核心原则: 总是先找到根本原因 (root cause) 再尝试修复。症状修复是失败的。
违反此流程即违反调试精神。
先进行根本原因调查，否则不修复 (NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST)
如果你没有完成第一阶段，你不能提出修复。
用于任何技术问题:
特别在以下情况使用:
不要跳过当:
你必须在进入下一阶段之前完成每个阶段。
在尝试任何修复之前:
仔细阅读错误信息
持续复现
检查最近的更改
在多组件系统中收集证据
当系统有多个组件 (CI → build → signing, API → service → database):
在提出修复之前，添加诊断插桩:
对于每个组件边界:
- 记录什么数据进入组件
- 记录什么数据离开组件
- 验证环境/配置传播
- 检查每一层的状态
运行一次以收集显示在哪里断裂的证据
然后分析证据以识别失败的组件
然后调查该特定组件
示例 (多层系统):
# Layer 1: Workflow
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
# Layer 2: Build script
echo "=== Env vars in build script: ==="
env | grep IDENTITY || echo "IDENTITY not in environment"
# Layer 3: Signing script
echo "=== Keychain state: ==="
security list-keychains
security find-identity -v
# Layer 4: Actual signing
codesign --sign "$IDENTITY" --verbose=4 "$APP"
这揭示了: 哪一层失败 (secrets → workflow ✓, workflow → build ✗)
追踪数据流 (Trace Data Flow)
当错误在调用堆栈深处时:
参见此目录中的 root-cause-tracing.md 获取完整的反向追踪技术。
快速版本:
在修复之前找到模式:
找到工作示例
对照参考进行比较
识别差异
理解依赖关系
科学方法:
形成单一假设
最小化测试 (Test Minimally)
在继续之前验证
当你不知道时
修复根本原因，而不是症状:
创建失败的测试用例
superpowers:test-driven-development skill 编写适当的失败测试实施单一修复
验证修复
如果修复无效
如果 3+ 修复失败: 质疑架构
表明架构问题的模式:
停止并质疑基本原理:
在尝试更多修复之前和你的人类伙伴讨论
这不是一个失败的假设 - 这是一个错误的架构。
如果你发现自己在想:
所有这些意味着: 停止。返回第一阶段。
如果 3+ 修复失败: 质疑架构 (见第四阶段, 步骤 5)
注意这些重定向:
当你看到这些: 停止。返回第一阶段。
| 借口 | 现实 |
|---|---|
| "问题很简单，不需要流程" | 简单问题也有根本原因。流程对于简单 bugs 更快。 |
| "紧急，没时间走流程" | 系统化调试比猜测和检查的盲目尝试更快。 |
| "先试试这个，然后调查" | 第一个修复设定了模式。从一开始就做对。 |
| "确认修复有效后我会写测试" | 未经测试的修复站不住脚。先测试证明它。 |
| "一次修复多个可以节省时间" | 无法隔离什么起作用。导致新 bugs。 |
| "参考太长，我会调整模式" | 部分理解保证 bugs。完整阅读。 |
| "我看到了问题，让我修复它" | 看到症状 ≠ 理解根本原因。 |
| "再一次修复尝试" (在 2+ 失败后) | 3+ 失败 = 架构问题。质疑模式，不要再次修复。 |
| 阶段 | 关键活动 | 成功标准 |
|---|---|---|
| 1. 根本原因 | 阅读错误，复现，检查更改，收集证据 | 理解什么和为什么 |
| 2. 模式 | 找到工作示例，比较 | 识别差异 |
| 3. 假设 | 形成理论，最小化测试 | 确认或新假设 |
| 4. 实施 | 创建测试，修复，验证 | Bug 解决，测试通过 |
如果系统调查揭示问题确实是环境性的、依赖时间或者是外部的:
但是: 95% 的 "无根本原因" 案例是不完整的调查。
这些技术是系统化调试的一部分，可在此目录中找到:
root-cause-tracing.md - 通过调用堆栈向后追踪 bugs 以找到原始触发器defense-in-depth.md - 找到根本原因后在多层添加验证condition-based-waiting.md - 用条件轮询替换任意超时相关 skills:
来自调试会话: