| name | systematic-debugging |
| description | 系统调试技能。遇到任何 Bug、测试失败或异常行为时，必须先找根本原因再提出修复方案，绝不允许猜测后直接修复。
触发方式：Bug、报错、测试失败、异常行为、崩溃、修复
Systematic debugging skill. Find root cause before proposing fixes. Never guess.
Trigger: bug, test fail, error, crash, fix, unexpected behavior
|
Systematic Debugging：系统调试
概述
随机修复浪费时间并制造新 Bug。快速补丁掩盖底层问题。
核心原则：永远先找根本原因，再提出修复方案。症状修复是失败。
违反这条规则的字面规定，就是违反其精神。
何时使用 | When to Use
遇到任何技术问题时使用——
- 测试失败
- 生产环境 Bug
- 异常行为
- 性能问题
- 构建失败
- 集成问题
特别适用于：
- 时间压力下（紧急情况让人倾向于猜测）
- "quick fix"看似显而易见时
- 已经尝试过多种修复时
- 上一次修复没有奏效时
- 你不完全理解问题时
铁律 | The Iron Law
未经根本原因调查，不得提出任何修复方案
（NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST）
如果尚未完成第一阶段，不得提出任何修复方案。
四阶段工作流程 | The Four Phases
Phase 1：根本原因调查 | Root Cause Investigation
在尝试任何修复之前：
-
仔细阅读错误信息
- 不要跳过错误或警告
- 它们通常包含确切的解决方案
- 完整阅读堆栈跟踪
- 记录行号、文件路径、错误代码
-
稳定复现
- 能可靠地触发吗？
- 具体步骤是什么？
- 每次都发生吗？
- 如果无法复现 → 收集更多数据，不要猜测
-
检查最近变更
- 什么变更可能导致这个问题？
- Git diff，最近的提交
- 新依赖、配置变更
- 环境差异
-
多组件系统收集证据
- 在提出修复之前，在每个组件边界添加诊断工具
- 运行一次收集证据，找出哪里出了问题
- 然后分析证据识别故障组件
- 然后调查那个特定组件
-
追踪数据流
- 错误值从哪里起源？
- 什么调用了它并传入了坏值？
- 一直追踪到找到源头
- 在源头修复，而非症状
Phase 2：模式分析 | Pattern Analysis
修复之前先找规律：
-
找类似的working例子
- 在同一代码库中找到类似的working代码
- 什么 working 的东西和这个 broken 的类似？
-
对比参考实现
- 如果在实现某个模式，阅读参考实现完全部
- 不要略读——读每一行
- 在应用之前完全理解这个模式
-
识别差异
- working 和 broken 之间有什么不同？
- 列出每一个差异，无论多小
- 不要假设"那不可能有关系"
-
理解依赖
- 这个需要什么其他组件？
- 什么设置、配置、环境？
- 它做什么假设？
Phase 3：假设与测试 | Hypothesis and Testing
科学方法：
-
形成一个单一假设
- 清楚陈述："我认为 X 是根本原因，因为 Y"
- 写下来
- 要具体，不要模糊
-
最小化测试
- 做最小的可能改变来测试假设
- 一次只改一个变量
- 不要一次修复多个东西
-
验证后再继续
- 成功了吗？ → 阶段 4
- 没成功？ → 形成新的假设
- 不要在上面叠加更多修复
-
当你不知道时
- 说"我不理解 X"
- 不要假装知道
- 寻求帮助
- 做更多研究
Phase 4：实施 | Implementation
修复根本原因，而非症状：
-
创建失败的测试用例
- 最简单的复现
- 可能的话用自动化测试
- 如果没有框架，用一次性测试脚本
- 必须在修复之前有
- 使用
superpowers:test-driven-development skill 来写正确的失败测试
-
实施单一修复
- 解决已识别的根本原因
- 一次只改一个
- 不要"顺便"改进
- 不要捆绑重构
-
验证修复
- 测试现在通过了吗？
- 其他测试仍然通过吗？
- 问题真的解决了吗？
-
如果修复不奏效
- 停
- 数：你尝试了多少次修复？
- 如果 < 3：回到阶段 1，用新信息重新分析
- 如果 ≥ 3：停下来质疑架构（见阶段 5）
- 在没有架构讨论的情况下不要尝试修复 #4
-
如果 3+ 次修复失败：质疑架构
- 每个修复都在不同地方暴露新的共享状态/耦合/问题
- 修复需要"大规模重构"才能实施
- 每个修复都在其他地方产生新症状
- 停，质疑基本假设
- 和你的搭档讨论后再尝试更多修复
红牌警告 - 停，按照流程来 | Red Flags - STOP and Follow Process
如果你发现自己在想：
- "先快速修复，回头再调查"
- "试试改 X，看看能不能 work"
- "加多个变更，跑测试"
- "跳过测试，我手动验证"
- "大概是 X，让我修一下"
- "我不完全理解但这可能会 work"
- "模式说 X 但我会调整它"
- "主要问题有这些：[列出修复方案但不调查]"
- 在追踪数据流之前提出解决方案
- "再来一次修复尝试"（已经尝试了 2+ 次）
- 每个修复都在不同地方暴露新问题
所有这些意味着：停。回到阶段 1。
如果 3+ 次修复失败： 质疑架构（见阶段 4.5）
常见合理化借口 | Common Rationalizations
| 借口 | 现实 |
|---|
| "问题简单，不需要流程" | 简单的问题也有根本原因。流程对简单 Bug 也很快。 |
| "紧急，没时间走流程" | 系统调试比瞎猜更快。 |
| "先试试这个，不行再调查" | 第一个修复设定了模式。从一开始就走对。 |
| "确认修复 work 后再写测试" | 没有测试的修复不会持久。测试优先才能证明它。 |
| "一次改多个能节省时间" | 无法隔离什么有效。会出新 Bug。 |
| "参考太长了，我会调整模式" | 部分理解保证出 Bug。完全读它。 |
| "我看到问题了，让我修" | 看到症状 ≠ 理解根本原因。 |
| "再来一次修复尝试"（2+ 次之后） | 3+ 次失败 = 架构问题。质疑模式，不要再次修复。 |
快速参考 | Quick Reference
| 阶段 | 关键活动 | 成功标准 |
|---|
| 1. 根本原因 | 读错误，复现，检查变更，收集证据 | 理解是什么和为什么 |
| 2. 模式 | 找 working 例子，对比 | 识别差异 |
| 3. 假设 | 形成理论，最小化测试 | 确认或新假设 |
| 4. 实施 | 创建测试，修复，验证 | Bug 解决，测试通过 |
支持技术 | Supporting Techniques
root-cause-tracing.md - 通过调用栈向后追踪 Bug 找到原始触发点defense-in-depth.md - 找到根本原因后在多层添加验证condition-based-waiting.md - 用条件轮询替换任意超时
相关 Skills
- superpowers:test-driven-development - 创建失败测试用例（阶段 4 第 1 步）
- superpowers:verification-before-completion - 在声称成功之前验证修复有效
真实影响 | Real-World Impact
- 系统方法：15-30 分钟修复
- 随机修复方法：2-3 小时折腾
- 第一次修复率：95% vs 40%
- 引入新 Bug：接近零 vs 常见
