fault-diagnosis

故障诊断

概述

猜测修复方法会浪费时间，还会引入新缺陷。快速打补丁会掩盖根本问题。

核心原则： 尝试任何修复之前，务必先找出根本原因。只处理症状就是失败。

没有例外。没有权宜之计。没有捷径。

首要原则

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

如果你尚未完成阶段 1，就无权提出修复方案。

适用场景

适用于任何技术问题：

• 测试失败
• 生产环境故障
• 行为异常
• 性能下降
• 构建失败
• 集成中断

以下情况尤其重要：

• 时间紧迫时（紧迫感容易让人忍不住猜测）
• “只要快速修一下”看起来显而易见时
• 你已经尝试过多种修复方法时
• 之前的修复未能解决问题时
• 你并未完全理解问题时

以下情况也不要跳过：

• 问题看起来很简单（简单的 Bug 也有根本原因）
• 你赶时间时（系统化调查比盲目尝试更快）
• 有人要求你立刻解决时（有条理地处理比反复折腾更快）

四个阶段

进入下一阶段之前，必须完成当前阶段。

阶段 1：调查根本原因

尝试任何修复之前：

1. 彻底阅读错误消息

   • 不要跳过错误或警告
   • 它们往往包含确切答案
   • 完整阅读堆栈跟踪
   • 记录行号、文件路径和错误代码

2. 可靠地复现问题

   • 你能否稳定触发问题？
   • 具体的复现步骤是什么？
   • 问题是否每次都会发生？
   • 如果无法复现，就收集更多数据，不要猜测

3. 检查近期变更

   • 哪些变更可能导致问题？
   • Git 差异、近期提交
   • 新依赖项、配置变更
   • 环境差异

4. 在多组件系统中收集证据

   当系统包含多个组件时（CI -> 构建 -> 签名、API -> 服务 -> 数据库）：

   提出修复方案之前，添加诊断检测：

   For EACH component boundary:
     - Log what data enters the component
     - Log what data exits the component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to collect evidence showing WHERE it breaks
   THEN analyze evidence to identify the failing component
   THEN investigate that specific component
   

   示例（多层系统）：

   # Layer 1: Orchestrator
   echo "=== Orchestrator state: ==="
   echo "TOKEN: ${TOKEN:+SET}${TOKEN:-UNSET}"
   
   # Layer 2: Build script
   echo "=== Build environment: ==="
   env | grep TOKEN || echo "TOKEN not in environment"
   
   # Layer 3: Signing module
   echo "=== Certificate state: ==="
   security list-keychains
   security find-identity -v
   
   # Layer 4: Actual operation
   codesign --sign "$IDENTITY" --verbose=4 "$ARTIFACT"
   

   这可以揭示： 哪一层发生故障（密钥 -> 协调器正常，协调器 -> 构建失败）

5. 追踪数据流

   当错误出现在调用堆栈深处时：

   请参阅本目录中的 root-cause-tracing.md，了解完整的反向追踪方法。

   简而言之：

   • 错误值从何处产生？
   • 哪个调用方将错误值传入此函数？
   • 持续向上追踪，直到找到源头
   • 在源头修复，而不是处理症状

阶段 2：模式分析

修复之前先找出模式：

1. 查找可正常工作的示例

   • 在同一代码库中查找类似的可运行代码
   • 哪些正常工作的代码与故障代码相似？

2. 与参考实现进行对比

   • 如果要实现某种模式，请完整阅读参考实现
   • 不要略读，要逐行阅读
   • 在应用模式之前，先彻底理解它

3. 找出差异

   • 正常工作与故障的部分有哪些不同？
   • 列出所有差异，无论多么细微
   • 不要想当然地认为“这无关紧要”

4. 了解依赖项

   • 这需要哪些其他组件？
   • 需要哪些设置、配置和环境？
   • 它依赖哪些假设？

阶段 3：假设与测试

采用科学方法：

1. 提出单一假设

   • 明确陈述：“我认为 X 是根本原因，因为 Y”
   • 把它写下来
   • 要具体，不要含糊

2. 进行最小化测试

   • 为验证假设，只做尽可能小的变更
   • 一次只改变一个变量
   • 不要同时修复多个问题

3. 验证后再继续

   • 问题解决了吗？是 -> 阶段 4
   • 没有解决？提出一个新假设
   • 不要在此基础上不断叠加修复

4. 遇到不懂的情况

   • 说“我不理解 X”
   • 不要假装自己知道
   • 寻求帮助
   • 进一步调查

阶段 4：实施

修复根本原因，而非表面症状：

1. 创建失败测试用例

   • 尽可能简单地复现问题
   • 尽可能编写自动化测试
   • 如果没有可用的测试框架，则编写一次性测试脚本
   • 修复前必须先创建测试用例
   • 使用 godmode:test-first 技能编写规范的失败测试

2. 实施单一修复

   • 解决已确认的根本原因
   • 一次只做一项更改
   • 不要顺手做其他改进
   • 不要打包进行重构

3. 验证修复

   • 现在测试通过了吗？
   • 是否导致其他测试失败？
   • 问题是否确实已解决？

4. 如果修复无效

   • 停止
   • 统计：你尝试过多少次修复？
   • 如果少于 3 次：返回阶段 1，结合新信息重新分析
   • 如果达到或超过 3 次：停止，并质疑架构（见下文第 5 步）
   • 未经架构讨论，不要尝试第 4 次修复

5. 如果 3 次或更多次修复均失败：质疑架构

   表明存在架构问题的模式：

   • 每次修复都会在不同位置暴露新的共享状态、耦合或问题
   • 修复需要“大规模重构”才能实施
   • 每次修复都会在其他地方产生新的症状

   停止并质疑基本设计：

   • 这种模式从根本上是否合理？
   • 我们是否只是凭惯性在坚持？
   • 应该重构架构，还是继续修复表面症状？

   尝试更多修复之前，先与人类搭档讨论

   这不是假设失败，而是架构存在缺陷。

防护准则——停止并遵循流程

如果你发现自己在想：

• “先快速修复，之后再调查”
• “只要试着改一下 X，看看会怎样”
• “一次应用多项更改，然后运行测试”
• “跳过测试，我手动验证”
• “问题大概出在 X，我来修一下”
• “我还没完全弄懂，但这样可能行”
• “模式建议这样做，但我会换种方式”
• “主要问题有这些：[未调查就列出修复方案]”
• 尚未追踪数据流就提出解决方案
• “再尝试修复一次”（已经尝试过 2 次或更多次）
• 每次修复都会在不同地方暴露新问题

这些念头都意味着：停止。返回阶段 1。

如果 3 次或更多次修复均失败：质疑架构（见阶段 4，第 5 步）

人类搭档提醒你偏离方向的信号

留意以下引导：

• “这不是没发生吗？”——你未经验证就做出了假设
• “这样能让我们看到……吗？”——你本该收集证据
• “别猜了”——你还没弄清楚就提出修复方案
• “再深入想想”——质疑基本设计，而不只是症状
• “我们卡住了吗？”（语气沮丧）——你的方法不起作用

**看到这些信号时：**停止。返回阶段 1。

认知陷阱

合理化借口	实际情况
“问题很简单，不需要流程”	简单问题也有根本原因。这个流程能快速处理简单错误。
“情况紧急，没时间走流程”	系统化诊断比盲目猜测和反复尝试更快。
“先试试这个，再调查”	第一次修复会为后续定下模式。从一开始就做好。
“确认修复有效后再写测试”	未经测试的修复站不住脚。先写测试才能证明修复有效。
“一次做多项修复可以节省时间”	无法确定哪项修复有效，还会引入新的错误。
“参考内容太长，我会调整一下模式”	理解不完整必然导致错误。请完整阅读。
“我看出问题了，我来修”	看到症状不等于理解根本原因。
“再尝试修复一次”（失败 2 次或更多次后）	失败 3 次或更多次意味着存在架构问题。请质疑这种模式，不要再次修复。

快速参考

阶段	关键活动	成功标准
1. 根本原因	阅读错误、复现问题、检查更改、收集证据	弄清楚是什么以及为什么
2. 模式	查找可正常运行的示例、进行对比	找出差异
3. 假设	提出理论、进行最小化测试	得到确认或提出新假设
4. 实施	创建测试、修复问题、验证	Bug 已解决，测试通过

调查未能发现根本原因时

如果系统性调查表明，问题确实由环境、时序依赖或外部因素导致：

1. 你已完成调查流程
2. 记录调查内容
3. 实施适当的处理措施（重试、超时、错误消息）
4. 添加监控/日志，以便日后调查

但是： 95% 的“未找到根本原因”案例都是调查不完整。

辅助方法

这些方法属于故障诊断的一部分，可在此目录中找到：

• root-cause-tracing.md - 沿调用栈反向追踪 Bug，找到最初的触发因素
• defense-in-depth.md - 找到根本原因后，在多个层级添加验证
• condition-based-waiting.md - 用条件轮询替代任意超时

相关技能：

• godmode:test-first - 用于创建失败的测试用例（阶段 4，步骤 1）
• godmode:completion-gate - 在宣告成功前，验证修复是否有效

实际影响

根据诊断过程：

• 系统性方法：15-30 分钟解决问题
• 随机修复方法：花费 2-3 小时盲目尝试
• 首次尝试修复成功率：95% vs 40%
• 引入的新 Bug：几乎为零 vs 经常发生