systematic-debugging

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

在尝试任何修复之前：

1. 仔细阅读错误信息

   • 不要跳过错误或警告
   • 它们通常包含确切的解决方案
   • 完整阅读堆栈跟踪
   • 记录行号、文件路径、错误代码

2. 稳定复现

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

3. 检查最近变更

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

4. 多组件系统收集证据

   • 在提出修复之前，在每个组件边界添加诊断工具
   • 运行一次收集证据，找出哪里出了问题
   • 然后分析证据识别故障组件
   • 然后调查那个特定组件

5. 追踪数据流

   • 错误值从哪里起源？
   • 什么调用了它并传入了坏值？
   • 一直追踪到找到源头
   • 在源头修复，而非症状

Phase 2：模式分析 | Pattern Analysis

修复之前先找规律：

1. 找类似的working例子

   • 在同一代码库中找到类似的working代码
   • 什么 working 的东西和这个 broken 的类似？

2. 对比参考实现

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

3. 识别差异

   • working 和 broken 之间有什么不同？
   • 列出每一个差异，无论多小
   • 不要假设"那不可能有关系"

4. 理解依赖

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

Phase 3：假设与测试 | Hypothesis and Testing

科学方法：

1. 形成一个单一假设

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

2. 最小化测试

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

3. 验证后再继续

   • 成功了吗？ → 阶段 4
   • 没成功？ → 形成新的假设
   • 不要在上面叠加更多修复

4. 当你不知道时

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

Phase 4：实施 | Implementation

修复根本原因，而非症状：

1. 创建失败的测试用例

   • 最简单的复现
   • 可能的话用自动化测试
   • 如果没有框架，用一次性测试脚本
   • 必须在修复之前有
   • 使用 superpowers:test-driven-development skill 来写正确的失败测试

2. 实施单一修复

   • 解决已识别的根本原因
   • 一次只改一个
   • 不要"顺便"改进
   • 不要捆绑重构

3. 验证修复

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

4. 如果修复不奏效

   • 停
   • 数：你尝试了多少次修复？
   • 如果 < 3：回到阶段 1，用新信息重新分析
   • 如果 ≥ 3：停下来质疑架构（见阶段 5）
   • 在没有架构讨论的情况下不要尝试修复 #4

5. 如果 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 常见