superpowers-systematic-debugging

name	superpowers-systematic-debugging
description	Use when encountering any bug, test failure, or unexpected behavior. Enforces systematic four-phase debugging: root cause investigation, pattern analysis, hypothesis testing, and evidence-based fix verification.

Superpowers 系统性调试

核心准则

随机修 bug 浪费时间内制造新 bug。快速补丁掩盖根本问题。

核心原则：永远先找根本原因再尝试修复。症状修复 = 失败。

违反调试流程的字面意思 = 违反调试流程的精神。

铁律

未经根本原因调查，不许修复

如果没完成第 1 阶段，就不能提出修复方案。

何时使用

用于任何技术问题：

• 测试失败
• 生产 bug
• 意外行为
• 性能问题
• 构建失败
• 集成问题

特别要用于：

• 时间压力大时（紧急情况容易猜）
• "就一个快速修复"看起来很明显时
• 已经尝试了多个修复时
• 上次修复没用时
• 没有完全理解问题时

四阶段流程

阶段 1：根本原因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

   • 不要跳过错误或警告
   • 通常包含准确解决方案
   • 读完堆栈跟踪
   • 记下行号、文件路径、错误码

2. 稳定复现

   • 能可靠地触发吗？
   • 具体步骤是什么？
   • 每次都发生吗？
   • 如果不能复现 → 收集更多数据，不要猜

3. 检查最近变更

   • 什么变更可能导致这个？
   • Git diff、最近提交
   • 新依赖、配置变更
   • 环境差异

4. 追踪数据流

   当错误在调用栈深处：

   • 坏值从哪里产生？
   • 什么调用时传入了坏值？
   • 一直追踪到找到源头
   • 在源头修复，不是在症状处

阶段 2：模式分析

修复前找到模式：

1. 找类似工作的例子

   • 在同一代码库找类似正常工作的代码
   • 什么能正常工作而什么坏了？

2. 对比参考

   • 如果在实现某个模式，彻底读完参考实现
   • 不要略读——每一行都要读
   • 应用前完全理解模式

3. 识别差异

   • 工作的和坏的区别是什么？
   • 列出每个差异，不管多小
   • 不要假设"那个不重要"

4. 理解依赖

   • 这个还需要什么其他组件？
   • 什么设置、配置、环境？
   • 它做什么假设？

阶段 3：假设与测试

科学方法：

1. 形成一个假设

   • 清晰陈述："我认为 X 是根本原因，因为 Y"
   • 写下来
   • 要具体，不要模糊

2. 最小化测试

   • 做最小可能的变更来测试假设
   • 一次只改一个变量
   • 不要一次修多个东西

3. 验证后再继续

   • 有效？→ 阶段 4
   • 无效？→ 形成新假设
   • 不要在顶上加更多修复

4. 当不知道时

   • 说"我不理解 X"
   • 不要假装知道
   • 寻求帮助
   • 做更多研究

阶段 4：实现

修复根本原因，不修复症状：

1. 创建失败的测试用例

   • 最简单的复现方式
   • 能自动化就自动化
   • 修复前必须有
   • 用 superpowers-tdd 技能写正确的失败测试

2. 实现单一修复

   • 解决识别的根本原因
   • 一次改一个
   • 不要"既然在这里"就改进
   • 不要捆绑重构

3. 验证修复

   • 测试现在通过了吗？
   • 其他测试坏了吗？
   • 问题真的解决了吗？

4. 如果修复没用

   • 停止
   • 数：已经尝试了多少次修复？
   • 如果 < 3：回到阶段 1，用新信息重新分析
   • 如果 ≥ 3：停止并质疑架构（见下）
   • 没有架构讨论不要再尝试修复 #4

5. 如果 3+ 修复都失败：质疑架构

   表明架构问题的模式：

   • 每个修复在不同地方揭示新的共享状态/耦合/问题
   • 修复需要"大规模重构"才能实现
   • 每个修复在其他地方产生新症状

   停止并质疑基本原理：

   • 这个模式根本上是合理的吗？
   • 我们是在"靠惯性坚持"吗？
   • 应该是重构架构还是继续修症状？

   在尝试更多修复之前与主人讨论

红旗

如果发现自己想：

• "先快速修复，以后再调查"
• "就试试改 X 看看行不行"
• "加多个变更，一起跑测试"
• "跳过测试，我手动验证"
• "大概是 X，让我修那个"
• "我没有完全理解但这可能行"
• "再试一次修复"（已经尝试了 2+ 次）
• 每个修复在不同地方揭示新问题

所有这些意味着：停止。回到阶段 1。

如果 3+ 修复失败： 质疑架构。

主人发出的信号（你在做错）

• "那没有发生吗？" - 你假定了没有验证
• "这会告诉我们……？" - 应该加了证据收集
• "别猜了" - 你在没理解的情况下提修复
• "再想清楚" - 质疑基本原理，不只是症状

看到这些时： 停止。回到阶段 1。

快速参考

阶段	关键活动	成功标准
1. 根本原因	读错误，复现，检查变更，收集证据	理解了什么和为什么
2. 模式	找工作例子，对比	识别差异
3. 假设	形成理论，最小测试	确认或新假设
4. 实现	创建测试，修复，验证	Bug 解决，测试通过

当过程显示"没有根本原因"时

如果系统性调查发现问题是真正环境相关、时序相关或外部的：

1. 已完成调查流程
2. 记录调查了什么
3. 实现适当处理（重试、超时、错误信息）
4. 为未来调查添加监控/日志

但是： 95% 的"没有根本原因"是调查不完整。