根因优先的铁律
明确规定未完成根因调查前不得提出任何修复方案,症状式修复视为失败。
BAIZE AI RESOURCE
Systematic-debugging
systematic-debugging 是 superpowers 的 AI Skill,要求在处理 Bug、测试失败或异常行为时先调查根因,再提出和验证修复方案。

systematic-debugging 是 obra/superpowers 仓库 skills 目录下的一个 AI Skill,面向需要处理 bug、测试失败、生产故障、性能问题、构建失败和集成问题的开发者。它的核心原则是:在尝试任何修复之前,必须先找到根因,症状式修复被视为失败。技能把调试过程拆成四个必须依次完成的阶段:根因调查(仔细阅读报错、稳定复现、检查近期变更、在多组件系统中加诊断埋点、沿调用栈回溯数据流)、模式分析(寻找可用的相似实现、完整阅读参考实现、列出所有差异、理解依赖)、假设与验证(提出单一假设、做最小改动验证、失败则重新假设而非叠加修复)、实施(先写失败测试用例、只做一处修复、验证修复且不破坏其他测试)。技能还规定,如果连续三次修复都失败,应停止继续尝试并质疑架构本身。它特别强调在时间压力大、看似只需一处快速修复、已经试过多个修复或问题尚未被完全理解时更要使用该流程。
明确规定未完成根因调查前不得提出任何修复方案,症状式修复视为失败。
依次完成根因调查、模式分析、假设与测试、实施修复,每个阶段完成前不得进入下一阶段。
在 CI、构建、签名或 API、服务、数据库等多层系统中,先在组件边界加诊断埋点,定位真正出错的层。
沿调用栈向上追溯错误值的来源,在源头而非症状处修复,配套 root-cause-tracing.md 说明完整方法。
若连续三次修复均失败,停止继续打补丁,转而讨论架构是否存在根本性问题。
使用场景线上出现异常行为但原因不明
按四阶段流程先复现并收集证据,定位根因后再提交修复,避免盲目打补丁。
使用场景CI、构建、签名等多层系统报错
在各组件边界加入诊断输出,运行一次以确定故障发生在哪一层,再深入该层调查。
使用场景已经尝试多个修复但问题依旧
停止继续叠加修复,回到阶段一重新分析,若累计三次失败则质疑架构设计。