why

原因

调查代码背后的动机和意图。

与 how 技能配套。how 说明代码做什么以及如何运作。why 说明促成代码形成当前样貌的因素。

下方的每个任务都会指定 pstack-models.mdc 规则中的一个角色行及其默认值。将 model 设为该行的值；如果规则或该行不存在，则使用默认值。如果规则中的值为 auto 或 inherit-parent，则不设置 model。如果 Task 工具拒绝某个 slug，则使用默认值并说明原因。如果默认值也被拒绝，则根据错误消息使用同一系列中最接近的有效 slug。

工作准则

以谨慎、审慎且精准的调查者身份行事。诚实区分已知信息与推断。阅读 references/epistemics.md，了解完整的置信度框架和措辞指南。综合者必须遵循这些要求。

第 1 步：了解目标和问题

解析用户的提问。目标通常是代码片段、模式、功能或具名设计决策。问题通常涉及设计理由、权衡、促成因素、外部约束、死代码或广泛的历史追溯。

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

第 2 步：确定代码锚点

在启动调查者之前，先将调查锚定到具体代码。你需要：

• 相关文件路径和行范围
• 关键符号（函数名、类名、常量）
• 初步提交列表，即最近几次修改目标的提交
• 合并提交中的 PR 编号（主题行中符合 (#1234) 模式的编号）

在此处直接整理这些信息。

# Blame target lines for last-touch commits
git blame -L <start>,<end> <file>

# Full file history, with patches, through renames
git log --follow -p -- <file>

# Last N commits touching the file, PR numbers visible
git log --oneline -20 -- <file>

# Extract PR numbers from a commit message
git log -1 --format=%B <commit>

对于任何实质性提交，使用 gh 获取 PR 正文和讨论：

gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews

将这些信息作为种子上下文（文件路径、符号、提交、PR 编号、关联的工单 ID）记录下来，并传递给调查者。

第 3 步：并行启动调查者（默认方式）

默认进行完整的并行调查。

探索

启动调查员之前，先列出 Cursor 环境中可用的 MCP。有可用工具映射时，使用该映射；否则，检查 Cursor 暴露的 mcps/ 目录，查找已启用的 MCP 服务。

将每个可用的 MCP 归入一个证据类别：

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

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

目标是制定完整的覆盖范围映射，而非追求最精简的映射。记录未覆盖的类别，不要跳过搜索。

在一条消息中启动所有符合条件的调查员，让它们并行运行。不要让一个 Agent 负责多个 MCP。

子 Agent 配置（各项）：

• subagent_type：generalPurpose
• model：why investigators 行中指定的模型；默认为 grok-4.7-xhigh-fast
• readonly：false（Agent 模式）。**不要使用 readonly/Ask 模式。**该模式会移除 MCP 访问权限，导致依赖 MCP 的调查员无法工作。调查员仍不应写入任何内容。

每位调查员都需要：

1. references/investigator-prompt.md 中的基础提示词
2. 所选 MCP 对应的类别指南 references/sources/<source>.md，根据 references/source-playbook.md 中的示例改编
3. 如果目标代码体现出防御性处理（空值检查、重试逻辑、超时处理、速率限制、功能标志、出口防护、OOM 处理），则还需提供跨领域指南 references/sources/incident-postmortem.md
4. 第 2 步中的代码锚点（文件路径、符号、提交哈希、PR 编号、工单 ID）
5. 用户的原始问题

调查员名册。每个可用证据类别分配一名

为每个拥有匹配 MCP 的类别启动一名调查员。每名调查员只负责一个工具或 MCP。

每个条目都说明类别，以及该类别独有的「原因」线索。用它来判断预期会得到什么结果、类别没有返回结果时该如何描述这一缺口，以及（仅在少数可证明无关的情况下）如何说明跳过的理由。

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 步：综合

启动一名综合子代理：

• subagent_type：generalPurpose
• model：why synthesizer 行中的模型，默认值为 claude-opus-5-5-max
• readonly：false（智能体模式）。综合器的质量检查会抽样核实引文，可能需要访问 MCP。Readonly／Ask 模式会移除 MCP，导致无法完成此项检查。

向综合器提供：

1. 调查员的发现，包括任何空结果以及附有理由的跳过类别
2. 第 2 步的代码锚点（文件路径、符号、提交哈希、PR 编号、工单 ID）
3. 用户的原始问题
4. references/epistemics.md 中的认识论框架
5. references/synthesizer-prompt.md 中的综合器提示词模板

第 5 步：呈现

将综合器的输出呈现给用户。你可以稍作编辑以提高可读性，或补充对话中的上下文，但不要改写置信度表述。

输出格式

输出结构应采用 references/synthesizer-prompt.md 中的格式：问题、相关代码、我们的发现、我们可以合理推断的内容、相互竞争的假设、我们不知道的内容、查阅的来源、置信度总结。可根据需要调整，但必须保留置信度区分；“查阅的来源”部分中，每位调查者占一行，包括没有返回结果或被跳过的调查者，并说明原因。

在“查阅的来源”部分之后，如果用户的 why 问题是实际修改此代码的前置问题，则将溯源发现转换为适合规划变更的一组约束：保留 / 更改 / 避免 / 风险。

常见错误，需避免

• 近因偏差。不要假设最新提交就具有权威性。当前形态往往是许多早期决策逐渐累积的结果。追溯源头。

参考文件

• references/epistemics.md。置信度层级和措辞指南。综合器必须遵循。
• references/investigator-prompt.md。调查子 Agent 的基础提示词模板。
• references/source-playbook.md。指向各类别操作手册的索引。
• references/sources/*.md。每个类别各有一份独立示例操作手册，另有一份横向适用的 incident-postmortem.md。向调查者提供与其类别匹配的单个文件，并根据可用的 MCP 进行调整。
• references/synthesizer-prompt.md。综合器子 Agent 的提示词模板，其中包含输出格式。