用途
Systematic Debugging 是一套用于排查技术问题的系统化流程技能。它适用于任何技术问题，包括测试失败、生产环境 bug、异常行为、性能问题、构建失败和集成问题。该技能的核心主张是：随机修复浪费时间并制造新 bug，快速补丁会掩盖底层问题，因此必须始终先找到根因再尝试修复，症状修复即失败。
主要能力
该技能定义了一条“铁律”：没有根因调查就不允许修复。如果未完成第一阶段，就不能提出修复方案。它提供四个必须依次完成的阶段：
-
根因调查：在尝试任何修复之前，仔细阅读错误信息和完整堆栈跟踪，记录行号、文件路径和错误码；一致地复现问题，确认触发步骤和是否每次都发生；检查近期变更，包括 git diff、最近提交、新依赖、配置变更和环境差异；在多组件系统中收集证据，在每个组件边界记录进入和退出的数据、验证环境/配置传播、检查各层状态，先运行一次以确定故障发生在哪一层，再分析证据定位失败组件；当错误位于调用栈深处时，沿调用栈向后追踪数据流，找到坏值来源并在源头修复。
-
模式分析：在修复前先找模式。定位同一代码库中类似的可工作代码；如果是在实现某个模式，完整阅读参考实现，不要略读；列出工作版本与故障版本之间的每一处差异，无论多小；理解依赖关系，包括所需的其他组件、设置、配置、环境以及所做的假设。
-
假设与测试：采用科学方法。形成单一假设，明确表述“我认为 X 是根因，因为 Y”并写下来；做最小可能的更改来测试假设，一次只改变一个变量，不要同时修复多个问题；验证后再继续，如果有效则进入第四阶段，如果无效则形成新假设，不要在原有修复上叠加更多修复；当不知道时，明确说“我不理解 X”，不要假装知道，应寻求帮助或进一步研究。
-
实施：修复根因而非症状。创建失败测试用例，尽可能使用最简单的复现方式，优先自动化测试，没有框架时可用一次性测试脚本，修复前必须拥有该测试；实施单一修复，针对已识别的根因，一次只做一个更改，不做“顺便改进”，不捆绑重构；验证修复，确认测试通过、其他测试未被破坏、问题确实解决。如果修复无效，停止并计数：尝试少于 3 次则返回第一阶段用新信息重新分析；尝试 3 次及以上则停止并质疑架构，不要在没有架构讨论的情况下尝试第 4 次修复。
使用方式
该技能以流程规范的形式使用，要求在每个阶段完成前不得进入下一阶段。资料中列出了红旗信号，一旦出现以下想法就应停止并返回第一阶段：例如“先快速修复，稍后再调查”“先试试改 X 看行不行”“添加多个更改然后跑测试”“跳过测试，我手动验证”“大概是 X，我来修它”“我不完全理解但可能有用”“模式说 X 但我会换个方式适配”“以下是主要问题：[未调查就列出修复]”、在追踪数据流之前提出解决方案、“再试一次修复”（已尝试 2 次以上）、每次修复都在不同地方暴露新问题。
资料还列出了人类伙伴发出的错误信号，例如“那没有发生吗？”表示未经验证就假设，“它会向我们展示……吗？”表示应该添加证据收集，“停止猜测”表示在不理解的情况下提出修复，“深入思考这个”表示应质疑根本而非症状，“我们卡住了？”（沮丧）表示方法无效。看到这些信号时应停止并返回第一阶段。
适用场景
该技能适用于任何技术问题，尤其在以下情况应特别使用：时间压力下（紧急情况容易诱使猜测）、“只需一个快速修复”看起来很明显时、已经尝试过多次修复时、之前的修复没有奏效时、不完全理解问题时。不应跳过的情况包括：问题看起来简单（简单 bug 也有根因）、正在赶时间（匆忙必然导致返工）、管理者要求立即修复（系统化比反复折腾更快）。
限制与配套
资料指出，如果系统化调查发现问题确实是环境性、时序相关或外部原因，则视为已完成流程，应记录调查内容、实施适当处理（重试、超时、错误消息）并添加监控/日志以供未来调查；但 95% 的“无根因”情况是调查不完整。该技能还包含配套技术文档：root-cause-tracing.md（沿调用栈向后追踪 bug 找到原始触发点）、defense-in-depth.md（找到根因后在多层添加验证）、condition-based-waiting.md（用条件轮询替代任意超时）。相关技能包括 superpowers:test-driven-development（用于第四阶段第一步创建失败测试用例）和 superpowers:verification-before-completion（在声称成功前验证修复有效）。资料还给出了实际影响数据：系统化方法修复需 15-30 分钟，随机修复方法需 2-3 小时反复折腾；首次修复率 95% 对 40%；引入新 bug 接近零对常见。