why

为什么

探究代码背后的动机和意图。配套的 how 技能回答代码做什么以及如何运作；why 则回答哪些因素促成了代码如今的形态。

以下所有子 Agent 均为只读。给它们的任务说明中包含已填好的提示词模板和所需参考文件，这些内容会直接粘贴进去或以绝对路径提供；说明还要求它们只读、仅检查、不写入，并且不执行会更改状态的 git 命令。以你拥有的相同工具访问权限启动每个子 Agent：没有 MCP 的调查者无法搜索其源码。根据 ~/.config/ox/models.md 为每个子 Agent 选择模型，并使用对应步骤指定的角色；将该行的模型和 effort 传给子 Agent 工具。如果该行是 inherit、文件中没有对应行，或文件的 # harness 行指定了不同的 harness，则两者都省略，让子 Agent 使用你的模型；如果文件不存在，也请建议用户运行 /setup-ox models。如果工具不接受某个条目，请使用它列出的最接近选项，并说明这一点。如果 harness 没有子 Agent 工具，则按顺序自行完成每个步骤。

工作原则

以谨慎、审慎且精准的调查者姿态开展工作。诚实区分已知事实与推断内容。完整的置信度框架和措辞指南见 EPISTEMICS.md。综合分析者必须遵循该指南。

步骤 1. 理解目标和问题

目标通常是一段代码、一种模式、一项功能或一个具名的设计决策。问题通常涉及设计理由、权衡、促成设计的边缘情况、外部约束、死代码或广泛的历史梳理。

如果目标含糊不清（例如“我们为什么要这样做？”却没有明确所指），请根据对话上下文（打开的文件、最近的编辑、刚刚讨论的内容）尽可能作出合理判断。简要说明你的理解，让用户在你理解有误时可以纠正，然后继续调查。

步骤 2. 确定代码锚点

开始调查前，先在线程中建立种子上下文：文件路径和行号范围、关键符号（函数、表、事件、导出项）、最近几次涉及目标的提交、合并提交中的 PR 编号（主题行中符合 (#1234) 模式的编号）以及任何关联的 issue ID。运行 git blame -L <start>,<end> <file> 获取最后修改提交，运行 git log --follow -p -- <file> 获取包含重命名在内的完整历史及补丁，运行 git log --oneline -20 -- <file> 查看可见 PR 编号的近期提交，并运行 git log -1 --format=%B <commit> 提取 PR 编号。然后针对所有实质性提交提取 PR 正文和讨论：gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews。

如果目标位于服务运行所用、但本仓库不拥有的资源中，或者服务目录并非 git 仓库，则应以该资源的上游仓库和服务运行的版本为锚点。SOURCES.md 说明了如何查找两者。

将此锚点提供给每位调查者和综合分析者。

步骤 3. 启动并行调查者

**默认进行完整的并行调查。**目标是绘制完整的覆盖图，而不是尽量精简。记录空结果，不要跳过搜索。

发现

在启动调查员之前，先列出你自己的工具列表中的 MCP，按服务分组，并包括那些架构尚未加载、仅显示名称的工具。将每个工具归入一个证据类别：

1. 源代码管理历史
2. 问题跟踪器
3. 长篇文档
4. 实时聊天
5. 基础设施可观测性
6. 错误跟踪
7. 产品分析

源代码管理始终可通过 git 和 gh 使用；如果代码托管在 GitHub 上，通过 gh 使用 GitHub Issues 即可覆盖问题跟踪器类别。对于其余类别，请根据 MCP 名称、服务说明、工具名称和资源描述进行分类。如果某个 MCP 可能属于多个类别，请选择与其主要证据相符的类别，并在覆盖范围图中记录模糊不清的情况。

每个有可用来源的类别都启动一名调查员；同时启动，让他们并发运行，每名调查员只负责一个工具或 MCP。不要让同一名 Agent 覆盖多个类别。每名调查员命名为 why investigator: <category>，并使用 explore 角色。

每名调查员的任务说明为填写完成的 INVESTIGATOR-PROMPT.md，另外还需包括：

• SOURCES.md 中该类别的部分，并根据分配给调查员的 MCP 进行调整
• SOURCES.md 中的事件背景部分，仅当目标代码看起来用于防御时（空值检查、重试、超时、速率限制、功能标志、距离或权限检查）
• 代码锚点和用户的原始问题

各类别最适合提供的内容

使用以下说明了解预期调查结果、在类别未返回结果时指出信息缺口，以及仅在极少数有确凿证据证明与目标无关时，说明跳过理由。

1. 源代码管理（git 历史、用于 PR 的 gh、代码注释、测试）。始终启动，这是唯一保证可用的来源。最擅长提供在评审期间记录的实现时决策依据。
2. 问题跟踪器（GitHub Issues，或 Linear 或 Jira MCP）。最擅长提供产品或用户层面的驱动因素：变更背后的错误报告或功能请求。
3. 长篇文档（文档网站、wiki 或类似 Notion 的 MCP）。最擅长提供在代码实现之前撰写的长篇设计依据。
4. 实时聊天（Discord、Slack 或 Teams MCP）。最擅长提供未写入文档的实时讨论。当 git、问题跟踪和文档记录较少时尤其重要。
5. 基础设施可观测性（Grafana、Datadog 或类似 MCP）。最擅长提供促使代码变更的运行时实际情况：超时、重试、速率限制。
6. 错误跟踪（Sentry 或类似 MCP）。最擅长提供促使编写防御性代码的具体错误：catch 块、nil 保护、类型检查、重试。
7. 产品分析（数据仓库或分析 MCP）。最擅长提供影响代码的使用数据：由功能标志控制的代码、数据迁移、“这个数字从何而来”。

何时跳过调查员

只有在最终的来源咨询记录中明确写出理由时，才能跳过。有效理由有两种：

• 此环境中没有该类别的可用来源。将其标记为信息缺口，而不是主动选择跳过：“跳过实时聊天。没有可用的匹配 MCP，因此无法搜索聊天记录。”
• 有确凿证据证明该来源与目标无关，而不仅仅是“可能无关”。门槛很高：“跳过错误跟踪。目标是一个构建脚本，不含运行时代码路径。”

如果目标是只有一次提交的变更，且 PR 描述已经包含完整答案，只有在确认所有可用类别的搜索都不会带来新信息后，才可以直接作答。请明确说明这一点。这种情况应很少见。

第 4 步：综合

启动一名名为 why synthesizer、使用 hardest tasks 角色的综合者。向它提供：

1. 调查员的发现，包括无结果的调查，以及有理由跳过的类别
2. 代码锚点
3. 用户的原始问题
4. EPISTEMICS.md 中的认知框架
5. SYNTHESIZER-PROMPT.md 中的综合者提示词

第 5 步：呈现

向用户呈现综合器的输出。你可以为清晰起见稍作编辑，或补充对话中的上下文，但不要改写置信度措辞。

输出格式

结构采用 SYNTHESIZER-PROMPT.md 中的格式：问题、相关代码、我们的发现、我们可以合理推断的内容、竞争性假设、我们不知道的内容、查阅的来源、置信度摘要。按需调整，但要保留置信度的区分，并确保「查阅的来源」中每位调查者各占一行，包括没有返回结果或被跳过的调查者，并注明原因。

在「查阅的来源」之后，如果用户的 why 问题是更改此代码的前置问题，请将代码沿革的发现转化为一组用于规划更改的约束：保留／更改／避免／风险。

需要避免的常见失败模式

• 近因偏差。不要假定最近一次提交就是权威依据。当前形态往往是许多早期决策逐步累积的结果。要追溯其沿革。