why

原因

从历史证据中还原塑造代码的力量。区分有文档记录的意图、证据支持的推断、合理的假设和未知之处。

代码是运作机制的证据，而非动机的证据。动机可能存在于源代码历史、评审、工单、文档、团队讨论、事故、遥测数据或产品数据中。

调查工作流

1. 明确问题

确定：

• 目标代码、模式、功能或决策；
• 用户想了解的具体理由；
• 问题中隐含的任何假设。

结合打开的文件、最近的编辑和对话上下文，理解含糊的指代。明确说明你的理解，让用户有机会纠正。只有在不同理解会导致调查内容存在实质性差异时才提问。

将用户提出的解释视为待检验的假设。

**完成条件：**目标和问题足够明确，能够界定相关证据。

2. 建立代码锚点

记录相关路径和行号、关键符号、最近修改它们的提交、追溯重命名前的历史，以及关联的评审或工单。可用的起始命令包括：

git blame -L <start>,<end> <file>
git log --follow -p -- <file>
git log --oneline -20 -- <file>
git log -1 --format=%B <commit>

使用可用的代码托管平台客户端或 API，读取评审说明和讨论。不要假设已安装特定的代码托管平台或工具。

记录路径、符号、提交、评审 ID、工单 ID、日期、作者和搜索词，以便在不同来源中重复使用。

**完成条件：**调查人员无需重新查找代码和问题涉及的时间范围，即可搜索其他系统。

3. 建立覆盖范围图

发现当前运行环境中可用的代码库和外部只读连接器。为每个连接器创建一条台账记录，再将每条记录映射到一个证据类别：

1. 源代码控制和代码评审；
2. 问题或工单跟踪；
3. 长篇文档；
4. 实时团队讨论；
5. 基础设施可观测性和事故；
6. 错误或异常跟踪；
7. 产品分析或数据仓库数据。

阅读 references/source-playbook.md，然后仅加载每个可用类别对应的操作手册。工具名称和架构由运行环境决定，而非由此技能指定。

默认搜索所有可用连接器；如果同一类别下的多个连接器保存着不同记录，也要全部搜索。将每条台账记录标记为 searched、unavailable、inaccessible 或 inapplicable，并说明原因和范围。只有当目标按其构造方式不可能涉及某个类别时，该类别才可标记为不适用。

**完成条件：**每个已发现的连接器都有搜索计划或具体的状态说明；即使没有可用连接器，台账中也包含全部七个类别。

4. 调查各个来源

如果有独立的只读 Agent 可用，就并行搜索各个连接器；否则依次搜索。每个连接器分配一个范围明确的调查通道；只有在多个连接器提供相同记录且使用相同查询词汇时，才将它们合并。此方法不得依赖特定的 Agent 提供方、模型或运行器配置。

使用 references/investigator-prompt.md 作为调查通道的约定。提供问题、代码锚点、类别操作手册，以及任何跨类别的事故调查角度。调查人员负责收集证据，而非回答问题。

针对每个来源：

• 先广泛搜索，再逐步缩小范围；
• 阅读完整的相关条目及其讨论；
• 在措辞至关重要时，记录带有稳定引用的准确引文；
• 记录查询、时间范围、无结果的搜索、矛盾之处和访问限制；
• 将跨来源线索交给相应类别处理，不要在不说明的情况下改变范围。

只有记录了产生该结果的搜索过程，无结果才会成为有用的证据。

**完成条件：**每个计划调查的类别都提供带引用的证据、记录完整的无结果搜索，或明确说明访问缺口。

5. 综合判断并校准置信度

阅读 references/epistemics.md 和 references/synthesizer-prompt.md。直接进行综合判断，或委派给一位只读综合分析者，该分析者可访问所有发现和代码锚点。

对每项主张进行分类：

• **直接：**来源明确说明了理由。
• **有依据：**多个间接来源得出的结论一致。
• **推断：**合理的解释，且推理链清晰可见。
• **推测：**合理的假设，但证据薄弱或存在相互竞争的证据。
• **未知：**检索未能回答该问题。

在引用之前抽查引文。指出矛盾，而不是为了叙述连贯而消解矛盾。最终编辑时保留置信度表述。

**完成标准：**每项理由主张都有置信度等级、与之相称的措辞，以及相邻证据或明确说明的证据缺口。

6. 呈现溯源过程

使用以下结构，仅省略确实没有内容的部分：

1. 问题
2. 代码锚点
3. 直接发现与有依据的发现
4. 合理推断
5. 相互竞争的假设
6. 未知项与缺口
7. 查阅的来源
8. 置信度总结

对于每个来源，说明检索了什么、发现了什么，包括无结果和跳过原因。读者应能快速核实引用的主张，并判断调查范围。

如果调查先于代码更改，请补充一组简明的约束：

• **保留：**仍有证据支持的行为或理由。
• **更改：**证据表明已过时的假设。
• **避免：**已被否定且其失效原因仍然成立的路径。
• **风险：**计划必须防范的缺口或不确定性。

**完成标准：**答案区分已知事实与推断，明确说明检索范围，并为用户提供可核实的证据，而不是听起来合理的故事。