name: systematic-debugging description: 在遇到任何错误、测试失败或意外行为时使用，在提出修复之前

系统化调试

概述

随机修复浪费时间并产生新错误。快速补丁掩盖了潜在问题。

核心原则： 在尝试修复之前，始终找到根本原因。症状修复是失败。

违反此流程的字面意思就是违反调试的精神。

铁律

没有根本原因调查，就没有修复

如果你没有完成阶段 1，你不能提出修复。

何时使用

用于任何技术问题：

测试失败
生产中的错误
意外行为
性能问题
构建失败
集成问题

在以下情况特别使用：

时间压力下（紧急情况使猜测变得诱人）
"只是一个快速修复"似乎很明显
你已经尝试了多个修复
之前的修复不起作用
你不完全理解问题

不要跳过当：

问题似乎很简单（简单错误也有根本原因）
你很匆忙（匆忙保证返工）
经理希望立即修复（系统化比折腾更快）

四个阶段

在继续下一个阶段之前，你必须完成每个阶段。

阶段 1：根本原因调查

在尝试任何修复之前：

仔细阅读错误消息
- 不要跳过错误或警告
- 它们通常包含确切的解决方案
- 完整阅读堆栈跟踪
- 注意行号、文件路径、错误代码
一致地重现
- 你能可靠地触发它吗？
- 确切的步骤是什么？
- 它每次都发生吗？
- 如果不可重现 → 收集更多数据，不要猜测
检查最近的更改
- 什么变化可能导致这个问题？
- Git diff，最近的提交
- 新依赖、配置更改
- 环境差异

在多组件系统中收集证据

当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：

在提出修复之前，添加诊断工具：

对于每个组件边界：
  - 记录进入组件的数据
  - 记录退出组件的数据
  - 验证环境/配置传播
  - 检查每一层的状态

运行一次以收集显示它在何处中断的证据
然后分析证据以识别失败的组件
然后调查该特定组件

示例（多层系统）：

# 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 了解完整的向后跟踪技术。

快速版本：
- 坏值起源于哪里？
- 什么用坏值调用了这个？
- 继续向上跟踪直到找到来源
- 在源头修复，而不是在症状处

阶段 2：模式分析

在修复之前找到模式：

找到工作示例
- 在同一代码库中定位类似的工作代码
- 什么工作与损坏的相似？
对照参考进行比较
- 如果实施模式，完整阅读参考实现
- 不要略读 - 阅读每一行
- 在应用之前完全理解模式
识别差异
- 工作和损坏之间有什么不同？
- 列出每个差异，无论多小
- 不要假设"那不可能重要"
理解依赖项
- 这需要哪些其他组件？
- 什么设置、配置、环境？
- 它做了什么假设？

阶段 3：假设和测试

科学方法：

形成单一假设
- 清楚地说明："我认为 X 是根本原因，因为 Y"
- 写下来
- 具体，不要模糊
最小化测试
- 进行尽可能小的更改以测试假设
- 一次一个变量
- 不要一次修复多个问题
在继续之前验证
- 它有效吗？是 → 阶段 4
- 不起作用？形成新假设
- 不要在顶部添加更多修复
当你不知道时
- 说"我不理解 X"
- 不要假装知道
- 寻求帮助
- 更多研究

阶段 4：实施

修复根本原因，而不是症状：

创建失败测试用例
- 尽可能简单的重现
- 如果可能，自动化测试
- 如果没有框架，一次性测试脚本
- 修复前必须有
- 使用 superpowers:test-driven-development 技能编写适当的失败测试
实施单一修复
- 解决已识别的根本原因
- 一次一个更改
- 没有"既然我在这里"的改进
- 没有捆绑重构
验证修复
- 测试现在通过了吗？
- 没有其他测试损坏？
- 问题实际解决了吗？
如果修复不起作用
- 停止
- 计数：你尝试了多少修复？
- 如果 < 3：返回阶段 1，用新信息重新分析
- 如果 ≥ 3：停止并质疑架构（下面的步骤 5）
- 不要在没有架构讨论的情况下尝试修复 #4
如果 3+ 修复失败：质疑架构

表示架构问题的模式：
- 每个修复在不同位置揭示新的共享状态/耦合/问题
- 修复需要"大规模重构"来实施
- 每个修复在其他地方创建新症状
停止并质疑基础：
- 这个模式在根本上是否合理？
- 我们是否"纯粹通过惯性坚持它"？
- 我们应该重构架构还是继续修复症状？
在尝试更多修复之前与你的合作伙伴讨论

这不是失败的假设 - 这是错误的架构。

危险信号 - 停止并遵循流程

如果你发现自己想：

"现在快速修复，稍后调查"
"只是尝试更改 X，看看是否有效"
"添加多个更改，运行测试"
"跳过测试，我会手动验证"
"可能是 X，让我修复它"
"我不完全理解，但这可能有效"
"模式说 X，但我会以不同方式适应它"
"以下是主要问题：[列出修复而不调查]"
在跟踪数据流之前提出解决方案
"再试一次修复"（当已经尝试 2+ 次时）
每个修复在不同位置揭示新问题

所有这些都意味着：停止。返回阶段 1。

如果 3+ 修复失败： 质疑架构（见阶段 4.5）

你合作伙伴的信号，表明你做错了

注意这些重定向：

"那不是正在发生吗？" - 你在没有验证的情况下假设
"它会显示我们...吗？" - 你应该添加证据收集
"停止猜测" - 你在不理解的情况下提出修复
"超思考这个" - 质疑基础，不仅仅是症状
"我们卡住了？"（沮丧）- 你的方法不起作用

当你看到这些： 停止。返回阶段 1。

常见合理化

借口	现实
"问题很简单，不需要流程"	简单问题也有根本原因。流程对简单错误很快。
"紧急情况，没有时间流程"	系统化调试比猜测和检查折腾更快。
"先试试这个，然后调查"	第一次修复设定了模式。从一开始就做对。
"我会在确认修复有效后编写测试"	未测试的修复不会坚持。先测试证明它。
"一次多个修复节省时间"	无法隔离什么有效。导致新错误。
"参考太长，我会适应模式"	部分理解保证错误。完整阅读它。
"我看到问题了，让我修复它"	看到症状 ≠ 理解根本原因。
"再试一次修复"（2+ 失败后）	3+ 失败 = 架构问题。质疑模式，不要再修复。

快速参考

阶段	关键活动	成功标准
1. 根本原因	阅读错误，重现，检查更改，收集证据	理解什么和为什么
2. 模式	找到工作示例，比较	识别差异
3. 假设	形成理论，最小化测试	确认或新假设
4. 实施	创建测试，修复，验证	错误解决，测试通过

当流程揭示"无根本原因"时

如果系统化调查显示问题确实是环境性的、时间依赖的或外部的：

你已经完成了流程
记录你调查的内容
实施适当的处理（重试、超时、错误消息）
添加监控/日志记录以供将来调查

但是： 95% 的"无根本原因"案例是不完整的调查。

支持技术

这些技术是系统化调试的一部分，在此目录中可用：

root-cause-tracing.md - 通过调用堆栈向后跟踪错误以找到原始触发器
defense-in-depth.md - 在找到根本原因后在多个层添加验证
condition-based-waiting.md - 用条件轮询替换任意超时

相关技能：

superpowers:test-driven-development - 用于创建失败测试用例（阶段 4，步骤 1）
superpowers:verification-before-completion - 在声称成功之前验证修复有效

实际影响

来自调试会话：

系统化方法：15-30 分钟修复
随机修复方法：2-3 小时折腾
首次修复率：95% vs 40%
引入的新错误：接近零 vs 常见

systematic-debugging

SKILL.md