用途:在 bug 排查过程中维护一份轻量草稿文档作为外部记忆,防止重复阅读已分析过的代码、记不清正在验证哪个假设,以及不知不觉陷入无关方向。核心原则是“写一次、后查阅”,读一行笔记比重读 200 行源码更快。文档不优先于写测试或跑测试:若在更新笔记与写测试之间选择,先写测试,之后再更新笔记。
文件与时机:在定位阶段创建 ~/tmp/investigate-<short-name>.md,短名应能辨识该调查,例如 investigate-concurrent-write.md。创建后通知用户并提供路径。当出现多个待跟踪假设、已读过超过 3 个文件/函数、即将重读已读代码,或调查将跨多轮测试循环时创建。
格式:包含标题(一行式 bug 描述)、Error(断言/崩溃信息与 file:line,写一次不再改)、Current Focus(一句话说明此刻在做什么)、Hypotheses(每条带状态与测试/证据)、Code Read(按 file:line-range 记录收获)、Tests(按 file:line 与测试名记录结果和含义)、Ruled Out(已排除项及原因)、Next(具体下一步与备选)。
规则:开始新方向前更新 Current Focus;为所做的事添加假设;每次重要动作后更新——读完函数或文件段落后写入 Code Read,形成或推翻假设后更新 Hypotheses,跑完测试后优先更新(记录跑了什么、结果如何、对当前假设意味着什么);不要往文档里倾倒大段代码,用 file:line 引用;不要重整或重新格式化文档,它是草稿不是报告;可加入简短示意图。
假设限制:同时最多 3 个活跃假设,要加第 4 个需先拒绝或合并一个;同时最多 1 个 [TESTING];每个假设必须有测试或具体测试计划。状态取值:[UNTESTED]、[TESTING]、[CONFIRMED]、[REJECTED]、[SUPERSEDED]。
限制:资料未提供本技能的安装命令、依赖或代码实现,也未说明收费与平台支持情况。