why

原因

调查代码背后的动机和意图。配套的 how skill 会说明代码做什么以及如何运作。why 则回答是什么因素促成了它现在的样子。

下面每个 spawn 都会指定 pstack models 配置中的一个角色行和默认值。调用 Skill 工具并使用 pstack-harness 来解析其模型、effort 和 agent 类型。其 Spawn a role 部分也介绍了配置缺失、inherit-parent 和被拒绝的值。

每个 spawn 都是 general-purpose，且 readonly: false（Agent 模式）。不要使用 readonly/Ask 模式。 它会剥离 MCP 访问权限，从而禁用由 MCP 支持的调查员以及综合者的引用抽查。调查员仍不应写入任何内容。

运作姿态

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

第 1 步：了解目标和问题

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

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

第 2 步：确定代码锚点

在启动调查员之前，先在线程中构建种子上下文：文件路径和行范围、关键符号（函数、类、常量）、涉及目标的最近几次提交、合并提交中的 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> -R <host>/<owner>/<repo> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews，其中 <host>/<owner>/<repo> 从 origin 的 fetch URL 获取。如果缺少 gh、未通过身份验证或查询失败，请在代码锚点中将这些 PR 标记为未读取，并在“查阅的来源”中说明这一缺口。将此锚点提供给每位调查员和综合者。

第 3 步：并行启动调查员

默认进行完整的并行调查。 目标是形成完整的覆盖图，而不是追求最少调查。记录空结果，不要跳过搜索。

发现

启动调查员之前，先从工具清单中列出此会话可用的 MCP 服务（名称带有 mcp__ 前缀的工具会标明所属服务）。

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

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

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

对于有匹配 MCP 的每个类别，启动一名调查员；在同一条消息中一次性启动，以便并行运行，每名调查员恰好负责一个工具或 MCP。不要让一名 Agent 负责多个 MCP。调用 Skill 工具并指定 pstack-harness 来启动。该工具的 Spawn a role 部分会解析角色，并构建此 CLI 的启动调用。model：使用 why investigators 行中的值，默认为 sonnet。

每名调查员的提示词由填充后的 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）。最擅长：塑造代码的产品和数据实际情况。对于由功能标志控制的代码、实验驱动的发布、数据迁移以及“这个数字从何而来”之类的问题尤其有用。

何时跳过调查者

只有在有明确的书面理由，并将其写入最终的 Sources Consulted 时，才能跳过。以下是两个有效理由：

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

如果范围评估表明目标只是一个简单的单次提交，且 PR 描述已包含完整答案，则只有在确认所有七类可用搜索都属于重复劳动后，才能直接作答。请明确说明这一点。这种情况应当很少见。

第 4 步：综合

启动一名综合者。model：采用 why synthesizer 行指定的模型，默认为 opus。提供给它：

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

第 5 步：呈现

向用户呈现综合者的输出。可以稍作润色以提高清晰度，或补充对话中的上下文，但不要改写置信度表述。

输出格式

结构应遵循 references/synthesizer-prompt.md：The Question、The Code in Question、What We Found、What We Can Reasonably Infer、Competing Hypotheses、What We Don't Know、Sources Consulted、Confidence Summary。可按需调整，但必须保留置信度区分；Sources Consulted 中每位调查者占一行，包括没有找到结果或被跳过的调查者，并说明理由。

如果用户的 why 问题是修改此代码的前置步骤，则在 Sources Consulted 之后，将代码沿革发现转化为用于规划修改的 Preserve / Change / Avoid / Risk 约束集。

常见失败模式

• 近因偏误。不要假定最近的提交就具有决定性。当前形态往往是许多早期决策逐步累积的结果。请追溯其沿革。