Superpowers 系统化调试助手
核心原则
- 随机尝试式修复会浪费时间并制造新 bug
- 先定位根因，再实施修复；只修症状等于失败
铁律（必须遵守）
在完成“根因调查”前，不得提出任何修复方案或代码改动建议。
适用场景（必须执行）
- 单测/集成测试失败
- 线上/预发 bug、偶现问题
- “不符合预期”的行为（含权限、数据、流程异常）
- 性能问题、构建失败、集成失败
- 多系统/多组件链路问题（前端/后端/API/DB/CI 等）
四阶段流程（必须按顺序）
阶段 1：根因调查（不允许修复）
- 仔细读错误信息
- 不跳过 warning/stack trace
- 记录文件路径、行号、错误码、关键上下文
- 稳定复现
- 明确“最小复现步骤”
- 如果不可稳定复现：先补采样与观测点，不要猜
- 对照近期变更
- 近期提交、配置、依赖、环境差异
- 多组件系统按边界采证
- 在组件边界记录“进入数据/退出数据/关键环境与配置/状态”
- 跑一次采证后，先回答“断在哪一层”，再深入该层
- 追溯数据流（从坏值反向追）
- 从报错点往上追：坏值从哪里来的？是谁传进来的？继续向上直到源头
- 在源头修复，而不是在下游加补丁
阶段 2：模式分析（先找规律）
- 找到同类“正常工作的”参考实现并完整阅读
- 列出“正常 vs 异常”所有差异（再小也要列）
- 明确依赖项与隐含假设（配置、权限、时序、环境变量、缓存、DB 状态）
阶段 3：假设与验证（科学法）
- 单一假设
- 用一句话明确：我认为根因是 X，因为证据 Y
- 最小验证
- 一次只改一个变量来验证假设
- 不通过就回到阶段 1/2
- 不要叠加多次“可能有用的改动”
阶段 4：实施修复（只修根因）
- 先准备回归证明
- 能写自动化测试则先写失败用例（建议配合 superpowers-TDD助手）
- 不能写测试则准备最小脚本/最小复现与验证步骤
- 实施单一修复
- 一次只做一类改动
- 不做“顺手重构/顺手优化”
- 验证修复有效
- 原始症状消失
- 相关测试/构建通过
- 无新增回归
停止条件（必须刹车）
- 连续 3 次修复尝试仍无效：停止继续“第 4 次尝试”，回到阶段 1 重新采证并重新审视架构假设
- 无法复现且缺少证据：先补观测，再讨论方案
与本仓库规则的互操作（必须遵守）
- 若属于缺陷/排障：以“缺陷修复工作流助手”为主流程，本技能作为其阶段内部的方法论（尤其用于根因分析）
- 若属于功能开发：可直接使用本技能定位问题，再进入写计划与实现