why

Why

调查代码背后的动机和意图。配套的 how 技能回答代码做什么以及如何运作。why 则回答促使代码形成当前形态的因素。

调度约定。 通过 provider-dispatch.md 解析每个已配置的角色。调查员需要父级的实时 MCP 接口，因此默认且受支持的可移植路径是 inherit-parent（或其别名 auto）。通过路径传递代码锚点。在 Codex 上，通过 codex-tools.md 解析剩余的 Claude 工具名称。根据 poteto-mode 技能的 Subagents 部分，为每个子 Agent 选择适合任务的工作量。

每条工作路径都保留 MCP 访问权限。不要选择会移除此权限的子 Agent 类型或执行模式，否则 MCP 支持的调查员将无法工作，综合者也无法进行引用抽查。调查员仍不应编写任何内容。

Operating Posture

以谨慎、审慎且精确的调查员身份开展工作。诚实说明哪些是已知事实，哪些是推断。阅读 references/epistemics.md，了解完整的置信度框架和措辞指南。综合者必须遵循该指南。

Step 1. Understand the Target and the Question

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

如果目标含糊不清（例如“我们为什么要这样做？”，但没有明确指向），请根据对话上下文尽力判断（打开的文件、最近的编辑、光标位置、刚刚讨论的内容）。简要说明你的理解，以便用户发现不对时及时纠正，然后继续。

Step 2. Establish the Code Anchor

启动调查员之前，先在内联内容中构建种子上下文：文件路径和行范围、关键符号（函数、类、常量）、最近修改目标的几次提交、合并提交中的 PR 编号（主题行中的模式 (#1234)），以及任何关联的工单 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。将此锚点提供给每位调查员和综合者。

Step 3. Spawn Parallel Investigators

默认执行完整的并行调查。 目标是获得完整的覆盖图，而非尽量精简。记录未发现结果，不要跳过搜索。

发现

启动调查员之前，先列出 Claude Code 环境中可用的 MCP。使用系统提示顶部的工具列表（每个 MCP 都会显示为前缀为 mcp__<server>__<name> 的工具）。否则，读取插件或项目中的 .mcp.json，或运行 claude mcp list。

将每个可用的 MCP 映射到一个证据类别：

1. 源代码管理历史
2. 问题／工单跟踪
3. 长篇文档
4. 实时团队聊天
5. 基础设施可观测性
6. 错误／异常跟踪
7. 产品分析数据仓库

始终可以通过 git 和 gh 使用源代码管理。对于其他六类，请根据 MCP 名称、服务说明、工具名称和资源描述进行分类。如果某个 MCP 可能属于多个类别，请选择与其主要证据相符的类别，并在覆盖范围映射中记录有歧义的情况。

为每个有匹配 MCP 的类别启动一名调查员，并在同一轮分发中同时启动，让他们并发运行，每人恰好负责一个工具或 MCP。不要让一名 Agent 覆盖多个 MCP。通过 why investigators, synthesizer 描述符将每名调查员路由到对应任务（默认值为 inherit-parent），并向其提供所分配的 MCP。调查员仍不得写入文件；即使 MCP 能力执行模式在机制上并非只读，这仍是工作要求。

每名调查员的提示词由填充后的 references/investigator-prompt.md 构成，另外还包括：

• 所选 MCP 对应的类别操作手册 references/sources/<source>.md，根据 references/source-playbook.md 中的示例进行调整
• 如果目标代码看起来具有防御性（空值检查、重试逻辑、超时处理、速率限制、功能标志、出口保护、OOM 处理），则还需包括 references/sources/incident-postmortem.md
• 代码锚点和用户的原始问题

调查员名单：每个可用证据类别一名

以下每个类别都各有其独特的“原因”线索，详见“最擅长”部分。请据此预判调查员可能带回的内容，指出某个类别没有返回结果时的缺口，并且只有在极少数可明确证明与问题无关的情况下，才据此说明为何跳过。

1. 源代码管理（git 历史、用于 PR 的 gh、代码注释、测试）。始终启动，这是唯一有保障的来源。最擅长：在评审过程中记录下来的实现时决策依据。
2. 问题／工单跟踪（例如 Linear、Jira、GitHub Issues、Plane、Shortcut MCP）。最擅长：产品或业务方面的驱动因素。当原因来自工程之外时，尤其有力。
3. 长篇文档（例如 Notion、Confluence、Google Docs、Coda MCP）。最擅长：以长篇形式记录、并在落地为代码之前写下的设计依据。
4. 实时团队聊天（例如 Slack、Discord、Microsoft Teams、Mattermost MCP）。最擅长：未曾写入文档的实时讨论。当源代码管理、工单和文档中的记录较少时，尤其重要。
5. 基础设施可观测性（例如 Datadog、New Relic、Honeycomb、Grafana、Splunk MCP）。最擅长：促使代码变更的基础设施与运行时实际情况。当目标代码会响应基础设施信号（超时、重试、速率限制、熔断器）时，尤其有力。
6. 错误／异常跟踪（例如 Sentry、Rollbar、Bugsnag、Airbrake MCP）。最擅长：促使防御性或纠正性代码出现的具体异常及错误演变过程。对于 catch 块、空值保护、类型检查、重试和其他防护措施，尤其有力。
7. 产品分析数据仓库（例如 Databricks、Snowflake、BigQuery、ClickHouse、dbt、Redshift MCP）。最擅长：影响代码设计的产品与数据实际情况。对于受功能标志控制的代码、由实验驱动的发布、数据迁移，以及“这个数字从何而来”之类的问题，尤其有力。

何时跳过调查员

只有在最终的“查阅来源”中明确写出理由时，才可以跳过。有效理由有两种：

• 此环境中没有适用于该类别的 MCP。应将其标记为缺口，而不是选择：「跳过实时团队聊天。没有匹配的 MCP 可用，因此无法搜索对话记录。」
• 有确凿证据证明来源不相关，而不是「可能不相关」。标准应当很高：「跳过错误／异常跟踪。目标是一个构建时脚本，没有运行时代码路径。」

如果范围评估表明，目标是一个只有单次提交、内容简单的项目，且 PR 描述已经包含完整答案，那么只有在确认所有七类可用搜索都不会提供额外信息后，才可以直接回答。应明确说明这一点。这种情况应当很少见。

第 4 步：综合

通过 why investigators, synthesizer 描述符（默认 inherit-parent）分派一名综合者。保留相关 MCP 访问权限，因为综合者的质量检查会抽查引用。它不会写入文件。向它提供：

1. 调查结果，包括无结果的情况，以及附有理由而跳过的类别
2. 代码锚点
3. 用户的原始问题
4. references/epistemics.md 中的认识论框架
5. references/synthesizer-prompt.md 中的综合者提示词模板

第 5 步：呈现

向用户呈现综合者的输出。可以稍作编辑以使内容更清晰，也可以补充对话中的背景信息，但不得改写置信度表述。

输出格式

结构应遵循 references/synthesizer-prompt.md：问题、相关代码、我们的发现、合理推断、相互竞争的假设、未知事项、查阅来源、置信度摘要。可酌情调整，但必须保持置信度层次清晰；“查阅来源”应为每名调查员各占一行，包括未找到结果或被跳过的调查员，并说明理由。

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

应避免的常见错误

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