用途
系统化调试用于处理任何技术问题：测试失败、生产环境缺陷、意外行为、性能问题、构建失败、集成问题。特别建议在以下情况下使用：时间压力大（紧急情况容易诱使猜测）、看似有“一个快速修复”方案、已经尝试过多种修复、此前的修复未生效、以及你不完全理解问题时。不要因为问题看起来简单、赶时间或管理者要求立即修复而跳过该流程。
核心原则与铁律
核心原则是：在尝试修复之前，始终先找到根本原因；仅修复症状属于失败。铁律为：没有先进行根本原因调查，就不允许修复。如果尚未完成阶段一，就不能提出修复方案。
四个阶段
必须完成每个阶段后才能进入下一阶段。
阶段一：根本原因调查
在尝试任何修复之前：仔细阅读错误信息（不要跳过错误或警告，完整阅读堆栈跟踪，记录行号、文件路径、错误代码）；稳定复现问题（能否可靠触发、具体步骤是什么、是否每次都发生；若无法复现，应收集更多数据而非猜测）；检查近期变更（Git diff、近期提交、新增依赖、配置变更、环境差异）。
对于多组件系统（如 CI → 构建 → 签名，或 API → 服务 → 数据库），在提出修复前应在每个组件边界添加诊断检测：记录进入组件的数据、记录离开组件的数据、验证环境/配置的传递、检查每一层的状态；运行一次以收集证据、确定在何处出错，然后分析证据以识别失败组件，再调查该特定组件。资料中给出的多层系统示例包括：在工作流层打印 secrets 可用性，在构建脚本层检查环境变量，在签名脚本层检查钥匙串状态与身份，以及用 codesign 执行实际签名并输出详细日志。这样可揭示是哪一层失败。
当错误位于调用栈深处时，应追踪数据流：坏值源自何处？谁用坏值调用了这里？持续向上追踪直到找到源头，并在源头修复，而不是在症状处修复。完整技术见配套文档 root-cause-tracing.md。
阶段二：模式分析
在修复前先找模式：寻找可工作的示例（在同一代码库中定位相似的可用代码，与出问题的代码对比）；与参考实现对比（若在实现某模式，应完整阅读参考实现，不要略读，逐行阅读，在应用前充分理解模式）；识别差异（列出可用与损坏之间的每一处差异，无论多小，不要假设“那不可能有影响”）；理解依赖（需要哪些其他组件、设置、配置、环境，以及它做了哪些假设）。
阶段三：假设与测试
采用科学方法：形成单一假设（清晰陈述“我认为 X 是根本原因，因为 Y”，写下来，要具体而非模糊）；最小化测试（对假设做最小的可能改动，一次只改一个变量，不要一次修复多个问题）；继续之前先验证（成功则进入阶段四；未成功则形成新假设，不要在原有基础上继续加修复）。当你不懂时，应说“我不理解 X”，不要假装知道，可以求助或继续研究。
阶段四：实施
修复根本原因，而非症状：创建失败测试用例（最简复现，可能时自动化测试，无框架时可用一次性测试脚本；修复前必须有此测试；撰写规范的失败测试可使用 superpowers:test-driven-development 技能）；实施单一修复（针对已识别的根本原因，一次只做一处更改，不要顺手做“既然来了就改改”的优化，不要捆绑重构）；验证修复（测试现在通过吗？其他测试是否被破坏？问题真的解决了吗？在声称成功前使用 superpowers:verification-before-completion 技能）。
如果修复无效：停止，数一数已尝试了多少个修复。若少于 3 个，回到阶段一，用新信息重新分析；若达到或超过 3 个，停止并质疑架构（见下），不要在未讨论架构的情况下尝试第 4 个修复。
3 个以上修复失败：质疑架构
表明存在架构问题的模式包括：每个修复都在不同位置暴露新的共享状态/耦合/问题；修复需要“大规模重构”才能实施；每个修复都在别处制造新症状。此时应停止并质疑根本：这种模式从根本上合理吗？我们是否只是“出于惯性在坚持”？应该重构架构还是继续修复症状？在尝试更多修复前与人类伙伴讨论。这不是失败的假设，而是错误的架构。
红旗信号：停止并遵循流程
若你发现自己有以下想法：“先快速修复，以后再调查”“就试试改 X 看看行不行”“加多个改动然后跑测试”“跳过测试，我手动验证”“大概是 X，我来修它”“我不完全理解，但这可能有效”“模式说是 X，但我会换个方式适配”“主要问题如下：[未调查就列出修复]”、在追踪数据流之前就提出解决方案、“再试一次修复”（当已经试过 2 次以上）、每个修复都在不同位置暴露新问题——所有这些都意味着：停止，回到阶段一。若已失败 3 次以上，则质疑架构。
人类伙伴的错误信号包括：“那难道没有发生吗？”（你未验证就假设）、“这会向我们展示……吗？”（你本应添加证据收集）、“别猜了”（你在不理解时就提出修复）、“深入思考这个”（质疑根本，而非仅症状）、“我们卡住了？”（沮丧，说明你的方法无效）。看到这些时：停止，回到阶段一。
常见借口与现实
“问题简单，不需要流程”——简单问题也有根本原因，流程对简单缺陷很快。“紧急，没时间走流程”——系统化调试比猜测试错更快。“先试试这个，再调查”——第一次修复就设定模式，一开始就要做对。“确认修复有效后再写测试”——未测试的修复不会持久，测试先行才能证明。“一次多个修复省时间”——无法隔离哪个有效，还会引入新缺陷。“参考太长，我自行适配模式”——部分理解必然导致缺陷，要完整阅读。“我看到问题了，我来修”——看到症状不等于理解根本原因。“再试一次修复”（在 2 次以上失败后）——3 次以上失败意味着架构问题，质疑模式，不要再修。
快速参考
阶段一根本原因：阅读错误、复现、检查变更、收集证据；成功标准是理解“是什么”和“为什么”。阶段二模式：寻找可用示例、对比；成功标准是识别差异。阶段三假设：形成理论、最小化测试；成功标准是确认或产生新假设。阶段四实施：创建测试、修复、验证；成功标准是缺陷解决、测试通过。
当流程显示“没有根本原因”
如果系统化调查显示问题确属环境性、时序相关或外部原因：你已完成流程；记录调查了什么；实施适当处理（重试、超时、错误信息）；为未来调查添加监控/日志。但要注意：95% 的“没有根本原因”案例都是调查不完整。
配套技术
以下技术属于系统化调试的一部分，位于同一目录：root-cause-tracing.md（通过调用栈向后追踪缺陷，找到最初触发点）；defense-in-depth.md（找到根本原因后在多层添加验证）；condition-based-waiting.md（用条件轮询替代任意超时）。
限制
资料未说明该技能的收费、价格、平台支持范围或具体安装方式；除上述目录内配套文档和提到的相关技能外，暂未提供其他集成或命令信息。该技能本质是流程指南，不包含自动化工具或代码实现。