name: 系统调试 description: 在遇到任何错误、测试失败或意外行为时使用，在提出修复之前 - 四阶段框架（根原因调查、模式分析、假设测试、实施）确保在尝试解决方案前先理解根本原因

系统调试

概述

随机修复浪费时间并创造新错误。快速补丁掩盖根本问题。

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

违反这个过程的精神就是违反调试的精神。

铁律

在根原因调查完成之前，不要尝试任何修复

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

何时使用

用于任何技术问题：

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

特别在以下情况下使用：

时间压力下（紧急情况让猜测变得诱人）
“只是一个快速修复”似乎显而易见
你已经尝试了多个修复
之前的修复没有工作
你没有完全理解问题

不要跳过当：

问题看起来简单（简单错误也有根原因）
你匆忙中（匆忙保证返工）
经理想要立即修复（系统化比乱猜更快）

四个阶段

你必须在进入下一个阶段之前完成每个阶段。

阶段1：根原因调查

在尝试任何修复之前：

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

在多组件系统中收集证据

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

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

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

运行一次以收集证据显示在哪里中断
然后分析证据以识别失败组件
然后调查那个特定组件

示例（多层系统）：

# 层1：工作流
echo "=== 工作流中的可用秘密： ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

# 层2：构建脚本
echo "=== 构建脚本中的环境变量： ==="
env | grep IDENTITY || echo "IDENTITY 不在环境中"

# 层3：签名脚本
echo "=== 钥匙链状态： ==="
security list-keychains
security find-identity -v

# 层4：实际签名
codesign --sign "$IDENTITY" --verbose=4 "$APP"

这揭示： 哪一层失败（秘密 → 工作流 ✓，工作流 → 构建 ✗）

追踪数据流

当错误在调用栈深处时：

所需子技能： 使用 superpowers:root-cause-tracing 进行反向追踪技术

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

阶段2：模式分析

在修复之前找到模式：

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

阶段3：假设和测试

科学方法：

形成单一假设
- 清楚地陈述：“我认为 X 是根原因，因为 Y”
- 写下来
- 具体，不模糊
最小化测试
- 做最小的可能更改来测试假设
- 一次一个变量
- 不要一次修复多个事情
在继续之前验证
- 它工作了吗？是 → 阶段4
- 没有工作？形成新假设
- 不要在上面添加更多修复
当你不理解时
- 说“我不理解 X”
- 不要假装知道
- 寻求帮助
- 研究更多

阶段4：实施

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

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

指示架构问题的模式：
- 每个修复揭示新的共享状态/耦合/问题在不同地方
- 修复需要“大规模重构”来实现
- 每个修复在其他地方创造新症状
停止并质疑基本原则：
- 这个模式根本上是合理的吗？
- 我们是不是“仅仅通过惯性坚持下去”？
- 我们应该重构架构而不是继续修复症状吗？
在尝试更多修复之前与你的 human partner 讨论

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

红旗 - 停止并遵循过程

如果你发现自己思考：

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

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

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

你的 human partner 的信号你做错了

注意这些重定向：

“那没有发生吗？” - 你没有验证就假设了
“它会显示我们…吗？” - 你应该添加了证据收集
“停止猜测” - 你在没有理解的情况下提出修复
“Ultrathink 这个” - 质疑基本原则，不仅仅是症状
“我们被困住了吗？”（沮丧） - 你的方法不工作

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

常见合理化

借口	现实
“问题简单，不需要过程”	简单问题也有根原因。过程对简单错误很快。
“紧急，没有时间进行过程”	系统调试比猜测和检查乱猜更快。
“先尝试这个，然后调查”	第一次修复设定模式。从一开始就做对。
“我确认修复工作后再写测试”	未经测试的修复不持久。首先测试证明它。
“一次多个修复节省时间”	不能隔离什么工作。导致新错误。
“参考太长，我会适应模式”	部分理解保证错误。完全阅读它。
“我看到问题，让我修复它”	看到症状 ≠ 理解根原因。
“再多一次修复尝试”（在2+失败后）	3+失败 = 架构问题。质疑模式，不要再修复。

快速参考

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

当过程揭示“无根原因”时

如果系统调查揭示问题确实是环境的、时间相关的或外部的：

你已经完成过程
记录你调查了什么
实施适当处理（重试、超时、错误消息）
为未来调查添加监控/日志

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

与其他技能集成

这个技能需要使用：

root-cause-tracing - 当错误在调用栈深处时必需（见阶段1，步骤5）
test-driven-development - 创建失败测试用例必需（见阶段4，步骤1）

互补技能：

defense-in-depth - 在找到根原因后添加多层验证
condition-based-waiting - 替换在阶段2识别的任意超时
verification-before-completion - 在声称成功之前验证修复工作

真实世界影响

从调试会话：

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