用途：在遇到任何 Bug、测试失败或非预期行为时，提供一套先找根因、再动手修复的系统化调试流程。核心原则是：修复前必须先完成根因调查；只治症状的补丁视为失败。
四个阶段（必须逐阶段完成）：
- 根因调查：仔细读错误信息与完整堆栈，稳定复现问题，检查近期变更（git diff、提交、依赖、配置、环境差异）。多组件系统（如 CI→构建→签名、API→服务→数据库）应先在各组件边界加诊断埋点，记录进入与离开的数据、验证环境与配置传递，运行一次定位出错层，再深入该组件。深层调用栈错误可按 root-cause-tracing.md 反向追溯数据来源，在源头而非症状处修复。完成后把根因发现写入 .planning/findings.md 的“## Debugging Findings”。
- 模式分析：在同一代码库中找可工作的相似代码，完整阅读参考实现（不要略读），逐条列出工作与故障版本之间的差异，理解依赖、配置与环境假设，并把发现追加到同一 findings.md。
- 假设与测试：写出单一明确假设（“我认为 X 是根因，因为 Y”），做最小改动、一次只验证一个变量；成功进入阶段 4，失败则形成新假设而不是叠加更多修复。每次测试结果追加到 .planning/progress.md 的 Test Results 表，学到的结论追加到 findings.md。
- 实现：先写可失败的最小复现测试（可借助 superpower-planning:tdd），再针对根因做单一修复，不做顺手改进与捆绑重构；随后验证当前测试通过、其他测试未被破坏、问题真正解决。
限制与红线：若已尝试 3 次以上修复仍失败，应停止继续修复，转而质疑架构是否存在根本问题，并与用户讨论；出现“先快速修一下、稍后再查”“大概是 X 我直接改”“一次改多处再跑测试”等想法时，应停止并回到阶段 1。资料同时说明，若确实查明问题属于环境、时序或外部因素，也算完成流程，应记录调查内容并实现重试、超时、错误提示等处理及后续监控日志。