investigation-notes

调查笔记

概述

调查 bug 时，请维护一份轻量级的临时文档，作为外部记忆。这样可以避免重复阅读已经分析过的代码、忘记当前正在验证的假设，以及不知不觉地钻进兔子洞。

核心原则： 记一次，之后查阅。重读一行笔记，比重读 200 行源码更快。

务必及时更新文档，记录当前关注点、假设，以及阅读代码和运行测试所得的结论。

务必在重读代码或提出新假设之前先查阅文档。如果文档中已有相关信息，就直接使用。如果信息不够，再读代码，然后补充更好的笔记。

文档的优先级永远低于编写或运行测试。 如果需要在更新笔记和编写测试之间做选择，请先编写测试，之后再更新笔记。

文档

在熟悉情况时（/investigate 的第 2 步）创建 ~/tmp/investigate-<short-name>.md。

简短名称应足以说明调查内容（例如，investigate-concurrent-write.md、investigate-pipe-zombie-state.md）。

创建后，通知用户并提供文件路径，以便他们在编辑器中打开。

格式

# Investigation: <one-line bug description>

## Error

<assertion/crash message, file:line — written once, never changes>

## Current Focus

<single sentence: what you are doing RIGHT NOW>

## Hypotheses

1. [TESTING] <one sentence> — test: <test name or "not yet written">
2. [REJECTED] <one sentence> — disproved by: <one sentence>
3. [CONFIRMED] <one sentence> — evidence: <test name + result>

## Code Read

- `file:line-range` — <what you learned, short paragraph or bullet>

## Tests

- `file:line` "test name" — <result + what it means, one sentence>

## Ruled Out

- <thing you investigated and eliminated, one sentence why>

## Next

1. <concrete next action>
2. <fallback>

创建

在以下情况下创建文档：

• 需要跟踪多个假设
• 已阅读超过 3 个文件或函数
• 准备重读已经读过的代码
• 调查将涉及多轮编写和运行测试

创建文档时，请填写 Error、Current Focus、当前假设，以及已经了解到的内容（根据已完成的工作补充“Code Read”和“Tests”）。

规则

• 务必在开始任何新的工作线程前更新“Current Focus”
• 务必为当前正在做的工作添加一个假设
• 务必在每次重要操作后更新文档：
  • 阅读函数或文件章节后 → 添加到“Code Read”
  • 形成或否定假设后 → 更新“Hypotheses”
  • 运行测试后 → 在进行任何其他操作之前更新文档。 记录：运行了什么测试、结果如何，以及这对当前假设意味着什么。这条要求不可妥协——花 30 秒记录，可以避免多次运行测试后忘记它们证明了什么，又退回去读代码。
  • 开始新的工作线程后 → 更新“Current Focus”
• 不要在文档中粘贴大量代码，而应使用 file:line 引用代码。
• 不要重组或重新格式化文档——这是临时记录，不是报告。
• 可以添加简短、简单的图示，帮助理解和记忆。

假设数量限制

• 同时最多有 3 个有效假设。 如果要添加第 4 个，必须先否定或合并其中一个。
• 同时最多有 1 个 [TESTING]。 先专注于一个假设并测试、解决，再继续下一个。
• 每个假设都必须有对应的测试，或有具体的测试编写计划。 “还需要进一步调查”不是有效状态——那只是披着标签的分析瘫痪。

有效状态：

• [UNTESTED] — 已提出，但尚未测试。必须尽快变为 [TESTING] 或 [REJECTED]。
• [TESTING] — 正在测试。一次只能有一个。
• [CONFIRMED] — 测试按预测复现了 bug。
• [REJECTED] — 测试否定了该假设，或证据将其排除。请说明原因。
• [SUPERSEDED] — 已被更具体的假设取代。请引用替代它的假设。