القائمة
当遇到任何 bug、测试失败或意外行为时，在提出修复之前必须使用
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
在开展任何创造性工作之前必须使用：创建功能、构建组件、添加能力或修改行为。在动手实现前，先探索用户意图、需求并制定设计。
当同时面对 2 个及以上相互独立、无共享状态且无顺序依赖的任务时必须使用本技能
当需要在一个独立会话中执行已撰写的实现计划，并通过检查点进行复核时必须使用
当实现完成、所有测试通过且需要决定如何集成工作时必须使用——通过呈现结构化的本地合并、创建 PR 或清理工作树等选项，指导开发工作的收尾
当收到代码审查反馈、准备采纳建议前必须使用，尤其当反馈表述不清或技术上可疑时——要求技术严谨与验证，禁止表面附和或盲目执行
当完成任务、实现主要功能或在合并前需要验证工作是否符合要求时必须使用
| name | systematic-debugging |
| description | 当遇到任何 bug、测试失败或意外行为时，在提出修复之前必须使用 |
随机修复只会浪费时间并引入新 bug。临时补丁会掩盖根本问题。
核心原则： 必须先找到根本原因，再尝试修复。只修症状就是失败。
违背流程的字面要求，就是违背调试的精神。
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
如果尚未完成第一阶段，就不能提出修复方案。
适用于任何技术问题：
尤其在以下情况下使用：
不要跳过此流程的情况：
必须按顺序完成每个阶段，然后才能进入下一阶段。
在尝试任何修复之前：
仔细阅读错误信息
稳定复现问题
检查近期变更
在 multi-component 系统中收集证据
当系统包含多个组件时（CI → build → signing、API → service → database）：
在提出修复方案之前，先添加诊断埋点：
对于每个组件边界：
- 记录进入组件的数据
- 记录离开组件的数据
- 验证环境/配置传递
- 检查每一层的状态
运行一次以收集证据，定位故障位置
然后分析证据，确定具体失效的组件
再针对该组件深入调查
示例（多层系统）：
# Layer 1: Workflow
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
# Layer 2: Build script
echo "=== Env vars in build script: ==="
env | grep IDENTITY || echo "IDENTITY not in environment"
# Layer 3: Signing script
echo "=== Keychain state: ==="
security list-keychains
security find-identity -v
# Layer 4: Actual signing
codesign --sign "$IDENTITY" --verbose=4 "$APP"
这会揭示： 哪一层出错（secrets → workflow ✓，workflow → build ✗）
追踪数据流
当错误出现在调用栈深处时：
请参阅本目录中的 root-cause-tracing.md，了解完整的反向追踪技术。
快速版本：
在修复之前先找到模式：
寻找可运行的示例
与参考实现对比
识别差异
理解依赖关系
使用科学方法：
形成单一假设
最小化验证
验证后再继续
当你不确定时
修复根本原因，而不是症状：
创建失败的测试用例
superpowers:test-driven-development skill实施单一修复
验证修复
如果修复无效
如果 3 次以上修复失败：质疑架构
表明存在架构问题的迹象：
停下来并质疑根本问题：
在尝试更多修复之前，先与人类伙伴讨论
这不是假设失败，而是架构错误。
如果你发现自己这样想：
以上任何一条都意味着：停下来，回到第一阶段。
如果 3 次以上修复失败： 质疑架构（见第四阶段第 5 步）
注意这些引导语：
当你看到这些信号时： 停下来，回到第一阶段。
| 借口 | 事实 |
|---|---|
| "问题很简单，不需要流程" | 简单问题也有根本原因。流程对简单 bug 同样快速。 |
| "情况紧急，没时间按流程" | 系统性调试比猜测式试错更快。 |
| "先试一下这个，不行再调查" | 第一次修复就会定下调子。从一开始就要做对。 |
| "等确认修复有效后再写测试" | 未经测试的修复无法保持。先写测试才能证明问题。 |
| "一次性改多处更省时间" | 无法隔离真正起作用的改动，还会引入新 bug。 |
| "参考太长，我按理解适配一下" | 一知半解必然导致 bug。必须完整阅读。 |
| "我看到问题了，我来修" | 看到症状 ≠ 理解根本原因。 |
| "再试一次修复"（已失败 2 次以上） | 3 次以上失败 = 架构问题。要质疑模式，而不是继续修。 |
| 阶段 | 关键活动 | 成功标准 |
|---|---|---|
| 1. 根本原因 | 阅读错误、复现、检查变更、收集证据 | 理解 WHAT 和 WHY |
| 2. 模式分析 | 寻找可运行示例、对比 | 识别差异 |
| 3. 假设验证 | 形成理论、最小化验证 | 假设被证实或提出新假设 |
| 4. 实施 | 创建测试、修复、验证 | bug 解决、测试通过 |
如果系统调查显示问题确实是环境相关、时序相关或外部因素：
但是： 95% 的"没有根本原因"都是调查不完整。
这些技术是系统性调试的一部分，本目录下均有相关文件：
root-cause-tracing.md - 从调用栈反向追踪 bug，找到原始触发点defense-in-depth.md - 找到根本原因后，在多层添加校验condition-based-waiting.md - 用条件轮询替代任意超时相关 skill：
来自真实调试会话的数据：