debug

在了解 Bug 的根本原因之前，不要修复它。排查从症状开始，但不能止步于此。

快速路径：如果错误输出直接显示了第一个原因，就跳过假设步骤。例如，堆栈中的一行直接指向了原因。不要跳过复现、回归测试或第 8 步中的 verify 技能。如果看起来显而易见的修复没能让复现首次通过，那就说明原因并不明显。此时要执行所有步骤。

1. 在复现 Bug 之前，先创建一个任务列表，将这些步骤逐项列入。如果已有任务列表，就将这些步骤添加进去。每个步骤各占一项。跳过某个步骤时，将其标记为已完成，并在内容中添加 skip: <reason>。快速路径要以这种方式跳过假设步骤。若要返回较早的步骤，请将该步骤及其后的每个步骤重新添加为新项目，然后删除被新项目替代的未完成项目。
2. 先复现 Bug。构建一个每次都会失败的最小复现。如果无法复现，就持续收集证据，直到能够复现：日志、输入和版本。不要猜测。
3. 阅读实际错误。沿着原因链找到最初的原因，而不是最接近的症状。
4. 提出一个假设，并写明能证实或推翻它的观察结果。在开始修复前先获取该观察结果：一条日志、一项断言或一个探针。如果还没有这类证据，就添加检测代码。检测代码要尽量简洁、易于移除，并在得到结论后将其移除。
5. 当两个假设相互竞争时，设计一个能判断哪个成立的观察方式。不要逐个尝试修复。
6. 一次只修复一个根本原因。发现其他问题（例如第二个 Bug）时，标记出来，但不要修复。死代码不算另一个问题。在修复之前，像 implement 那样，删除修复所涉及的每个文件中的死代码。即使该 Bug 未涉及这些代码，也要这样做。死代码包括没有调用方使用的函数、导入项和参数，以及没有调用方会进入的分支；也包括过时的标记，以及重复检查边界处已完成检查的验证器；还包括复述代码或为变通方案辩护的注释。若非目标范围明确排除死代码，则予以保留。对于会添加保护逻辑、捕获处理或辩护性注释的修复，请先阅读 修复根本原因。当同一原因也可能出现在其他地方，或故障只在重启后出现时，也要阅读该文档。
7. 添加本可以捕获此 Bug 的回归测试。该测试在旧代码上失败，在修复后通过。
8. 报告修复之前，阅读 verify 技能并遵循其要求。你的报告会声称 Bug 已修复，而 verify 会验证这一说法。如果 Bug 出现在某个切片中，则完整门禁要等到该切片提交后再运行。

规则：

• 不要随机尝试多种修复，看看哪种有效。
• 连续三次假设被推翻后，停止循环。如果现有证据无法支持复现，也要停止。然后报告尝试过什么、缺少哪项观察结果，并由用户决定。
• 如果修复未能让复现通过，说明假设错误。返回第 4 步。不要保留失败的修复，再叠加第二个修复。如果两个失败的修复基于同一个前提，请阅读 检验前提。
• 如果根本原因暴露出设计问题，就明确指出。提出对重新设计运行 drill。不要用变通方案掩盖问题。
• 如果经过多个假设才找到原因，请提出一个成本低且持续启用的信号。它可以是一条日志、一项指标或一条断言，能够立即揭示该原因。征得用户同意后再添加。