why

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Why

为什么

Investigate the motivation and intent behind code.

Companion to the

how

skill.

how

answers what the code does and how it works.

why

answers what forces led to its shape.

Each spawn below names a role line in the

pstack-models.mdc

rule and a default. Set

model

to that line's value, or to the default if the rule or the line is missing. Leave

model

unset when the value is

auto

inherit-parent

. If the Task tool rejects a slug, use the default and say so. If it rejects the default, use the closest valid slug of the same family from its error message.

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

how

skill 的配套 skill。

how

回答代码做什么以及如何运作；

why

回答是哪些因素促成了它如今的形态。

下面每次 spawn 都引用

pstack-models.mdc

rule 中的一条角色配置行及其默认值。如果 rule 或该行不存在，则将

model

设为默认值。当值为

auto

或

inherit-parent

时，不要设置

model

。如果 Task tool 拒绝某个 slug，请改用默认值并说明这一点。如果默认值也被拒绝，请根据错误消息选择同一 family 中最接近的有效 slug。

Operating Posture

操作姿态

Operate as a careful, cautious, and precise investigator. Be honest about what you know vs what you're inferring. Read

references/epistemics.md

for the full confidence framework and phrasing guide. The synthesizer must follow it.

以谨慎、审慎且精准的调查者身份工作。要诚实区分已知事实与推断内容。完整的置信度框架和措辞指南见

references/epistemics.md

。synthesizer 必须遵循该指南。

Step 1. Understand the Target and the Question

第 1 步：理解目标与问题

Parse what the user is asking. The target is usually a chunk of code, a pattern, a feature, or a named design decision. The question is usually a design rationale, a tradeoff, a motivating edge case, an external constraint, dead code, or a broad history sweep.

If the target is vague ("why do we do it this way?" with no clear referent), make your best guess from conversation context (open files, recent edits, cursor location, what was just discussed). State your interpretation briefly so the user can redirect if you're off, then proceed.

解析用户提出的问题。目标通常是一段代码、一种模式、一个功能，或一项明确的设计决策。问题通常涉及设计缘由、权衡取舍、促使实现落地的边缘场景、外部约束、dead code，或广泛的历史追溯。

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

Step 2. Establish the Code Anchor

第 2 步：建立代码锚点

Before spawning investigators, anchor the investigation in concrete code. You need:

The relevant file path(s) and line range(s)
The key symbols (function names, class names, constants)
An initial commit list. The last few commits touching the target.
PR numbers from merge commits (pattern
```
(#1234)
```
in the subject line)

Build this inline.

bash

undefined

在 spawn 调查者之前，用具体代码为调查建立锚点。你需要：

相关文件路径和行号范围
关键符号（函数名、类名、常量）
初始 commit 列表，即最近触及目标的几个 commit
从 merge commit 中提取的 PR 编号（主题行中的模式为
```
(#1234)
```
）

在当前步骤中直接构建这些信息。

bash

undefined

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>


Pull PR bodies and discussion via `gh` for any substantive commits:

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

Capture this as seed context (file paths, symbols, commits, PR numbers, linked ticket IDs). Pass it to the investigators.

git log -1 --format=%B <commit>


对于任何实质性 commit，使用 `gh` 拉取 PR 正文和讨论：

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

将这些信息作为种子上下文（文件路径、符号、commit、PR 编号、关联 ticket ID）捕获下来，并将其传给调查者。

Step 3. Spawn Parallel Investigators (default posture)

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

Default to the full parallel investigation.

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

Discovery

发现

Before spawning investigators, list the available MCPs from the Cursor environment. Use the available-tools map when present. Otherwise inspect the

mcps/

directory Cursor exposes for enabled MCP servers.

Map each available MCP to one evidence category:

Source control history
Issue / ticket tracker
Long-form documents
Real-time team chat
Infrastructure observability
Error / exception tracking
Product analytics warehouse

Source control is always available through git and

gh

. For the other six, classify using the MCP name, server instructions, tool names, and resource descriptors. If an MCP could fit more than one category, choose the one matching its primary evidence. Record ambiguous cases in the coverage map.

Aim for a complete coverage map, not a minimal one. Document the null, don't skip the search.

Launch all matching investigators in a single message so they run concurrently. Don't ask one agent to cover multiple MCPs.

Subagent config (each):

```
subagent_type
```
:
```
generalPurpose
```

model

: the

why investigators

line, default

grok-4.7-xhigh-fast

```
readonly
```
:
```
false
```
(agent mode). Do not use readonly/Ask mode. It strips MCP access, which disables MCP-backed investigators entirely. Investigators still shouldn't write anything.

Each investigator gets:

The base prompt from
```
references/investigator-prompt.md
```
The category playbook
```
references/sources/<source>.md
```
for the selected MCP, adapted from the examples in
```
references/source-playbook.md
```
The cross-cutting
```
references/sources/incident-postmortem.md
```
if the target code looks defensive (null checks, retry logic, timeout handling, rate limiting, feature flags, egress guards, OOM handlers)
The code anchor from Step 2 (file paths, symbols, commit hashes, PR numbers, ticket IDs)
The user's original question

在 spawn 调查者之前，列出 Cursor 环境中可用的 MCP。如果存在 available-tools map，则使用它；否则检查 Cursor 暴露的

mcps/

目录，以识别已启用的 MCP server。

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

源代码管理历史
问题 / 工单跟踪器
长文文档
实时团队聊天
基础设施可观测性
错误 / 异常追踪
产品分析数据仓库

源代码管理始终可通过 git 和

gh

使用。对于其余六类，依据 MCP 名称、server 说明、工具名称和资源描述符进行分类。如果某个 MCP 可能属于多个类别，请选择与其主要证据最匹配的一个。在覆盖映射中记录有歧义的情况。

目标是建立完整的覆盖映射（coverage map），而不是最小覆盖。记录空结果，不要跳过搜索。

在同一条消息中启动所有匹配的调查者，让它们并发运行。不要让一个 agent 覆盖多个 MCP。

每个 subagent 的配置：

```
subagent_type
```
：
```
generalPurpose
```

model

：

why investigators

行，默认值为

grok-4.7-xhigh-fast

```
readonly
```
：
```
false
```
（agent mode）。不要使用 readonly/Ask mode。 它会剥离 MCP 访问权限，从而完全禁用基于 MCP 的调查者。调查者仍不应写入任何内容。

每个调查者获得：

```
references/investigator-prompt.md
```
中的基础 prompt
针对所选 MCP 的类别 playbook
```
references/sources/<source>.md
```
，并根据
```
references/source-playbook.md
```
中的示例进行调整
如果目标代码看起来具有防御性（null checks、retry logic、timeout handling、rate limiting、feature flags、egress guards、OOM handlers），还应提供跨领域的
```
references/sources/incident-postmortem.md
```
第 2 步中的代码锚点（文件路径、符号、commit hash、PR 编号、ticket ID）
用户的原始问题

Investigator roster. One per available evidence category

调查者名单。每个可用证据类别一个

Spawn one investigator per category that has a matching MCP. Each owns exactly one tool or MCP.

Each entry names the category and the kind of "why" it uniquely surfaces. Use it to know what to expect back, how to name a gap when a category returns empty, and (only in the rare provably-irrelevant case) to justify a skip.

Source control investigator. Git history,
```
gh
```
for PRs, code comments, tests. Always spawn. The only guaranteed source. Best at surfacing implementation-time rationale captured during review.
Issue / ticket tracker investigator (e.g. Linear, Jira, GitHub Issues, Plane, Shortcut MCP). Best at surfacing the product or business forcing function. Strongest when the why is external to engineering.
Long-form documents investigator (e.g. Notion, Confluence, Google Docs, Coda MCP). Best at surfacing long-form design rationale. Where the why is written out before it becomes code.
Real-time team chat investigator (e.g. Slack, Discord, Microsoft Teams, Mattermost MCP). Best at surfacing real-time deliberation that never reached a doc. Especially important when the source control, ticket, and doc paper trail is thin.
Infrastructure observability investigator (e.g. Datadog, New Relic, Honeycomb, Grafana, Splunk MCP). Infra/runtime view. Best at surfacing infrastructure and runtime reality that motivated the code. Strongest when the target reacts to an infra signal (timeouts, retries, rate limits, circuit breakers).
Error / exception tracking investigator (e.g. Sentry, Rollbar, Bugsnag, Airbrake MCP). Best at surfacing the specific exceptions and error trajectories that motivated defensive or corrective code. Strongest for catch blocks, null guards, type checks, retries, and other defenses.
Product analytics warehouse investigator (e.g. Databricks, Snowflake, BigQuery, ClickHouse, dbt, Redshift MCP). Product/data view. Best at surfacing product and data reality that shaped the code. Strongest for flag-gated code, experiment-driven ships, data migrations, and "where did this number come from" questions.

对于每个有匹配 MCP 的类别，spawn 一个调查者。每个调查者只负责一个工具或 MCP。

每个条目都会说明类别，以及该类别独有的“why”信息。借助它来判断预期返回结果、在某类别返回空结果时如何描述缺口，以及仅在极少见的可证明无关情形下为跳过类别提供理由。

源代码管理调查者。Git 历史、通过
```
gh
```
获取的 PR、代码注释和测试。始终 spawn；这是唯一有保证的证据源。最擅长揭示评审期间记录下来的实现阶段缘由。
问题 / 工单跟踪器调查者（如 Linear、Jira、GitHub Issues、Plane、Shortcut MCP）。最擅长揭示产品或业务层面的推动因素。当 why 存在于工程之外时尤其有力。
长文文档调查者（如 Notion、Confluence、Google Docs、Coda MCP）。最擅长揭示长篇设计缘由。尤其适合查找在代码出现之前就已写明的 why。
实时团队聊天调查者（如 Slack、Discord、Microsoft Teams、Mattermost MCP）。最擅长揭示从未进入文档的实时讨论。当源代码管理、ticket 和文档留下的书面证据链较薄弱时尤其重要。
基础设施可观测性调查者（如 Datadog、New Relic、Honeycomb、Grafana、Splunk MCP）。提供基础设施 / 运行时视角。最擅长揭示促使代码形成的基础设施与运行时现实。当目标代码会对 infra 信号（timeouts、retries、rate limits、circuit breakers）作出响应时尤其有效。
错误 / 异常跟踪调查者（如 Sentry、Rollbar、Bugsnag、Airbrake MCP）。最擅长揭示促使防御性或纠正性代码产生的具体异常与错误轨迹。对于 catch 块、null guard、类型检查、retries 和其他防御机制尤其有效。
产品分析数据仓库调查者（如 Databricks、Snowflake、BigQuery、ClickHouse、dbt、Redshift MCP）。提供产品 / 数据视角。最擅长揭示塑造代码的产品与数据现实。对于 flag-gated code、实验驱动的发布、数据迁移，以及“这个数字从何而来”类问题尤其有效。

When to skip an investigator

何时可以跳过调查者

Only skip with an explicit, written justification that goes in the final "Sources Consulted" section. Two valid reasons:

No MCP is available for that category in this environment. Flag this as a gap, not a choice. Example: "Real-time team chat skipped. No matching MCP available, so the conversational record was not searchable."
The source is provably irrelevant, not just "probably irrelevant." A high bar. Example: "Error / exception tracking skipped. Target is a build-time script with no runtime code path."

If your scope assessment suggests a single-commit trivial target where the PR description already contains the complete answer, you may answer inline only after confirming all seven available category searches would be redundant. Say so explicitly. This should be rare.

仅可在有明确书面理由时跳过调查者，且该理由必须写入最终的“已查阅来源（Sources Consulted）”部分。有两种有效理由：

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

如果范围评估表明目标是一个仅涉及单个 commit 的简单对象，且 PR 描述已包含完整答案，那么只有在确认七类可用证据搜索都会造成重复后，才可以内联回答。必须明确说明这一点。这种情况应当很少见。

Step 4. Synthesize

第 4 步：综合

Spawn one synthesizer subagent:

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
: the
```
why synthesizer
```
line, default
```
claude-opus-5-5-max
```
```
readonly
```
:
```
false
```
(agent mode). The synthesizer's quality check spot-verifies citations, which can require MCP access. Readonly/Ask mode strips MCPs and defeats that.

The synthesizer gets:

The investigator findings, including any null results and any categories skipped with justification
The code anchor from Step 2 (file paths, symbols, commit hashes, PR numbers, ticket IDs)
The user's original question
The epistemics framework from
```
references/epistemics.md
```
The synthesizer prompt template from
```
references/synthesizer-prompt.md
```

Spawn 一个 synthesizer subagent：

```
subagent_type
```
：
```
generalPurpose
```
```
model
```
：
```
why synthesizer
```
行，默认值为
```
claude-opus-5-5-max
```
```
readonly
```
：
```
false
```
（agent mode）。synthesizer 的质量检查会抽查引用，这可能需要 MCP 访问权限。readonly/Ask mode 会剥离 MCP，从而使该检查失效。

synthesizer 获得：

调查者的发现，包括空结果以及被跳过并附有理由的类别
第 2 步中的代码锚点（文件路径、符号、commit hash、PR 编号、ticket ID）
用户的原始问题
```
references/epistemics.md
```
中的认知框架
```
references/synthesizer-prompt.md
```
中的 synthesizer prompt 模板

Step 5. Present

第 5 步：呈现

Take the synthesizer's output and present it to the user. You may lightly edit for clarity or add context from the conversation, but do not rewrite the confidence language.

获取 synthesizer 的输出并呈现给用户。可以为清晰性略作编辑，或补充对话中的上下文，但不要改写置信度措辞。

Output Format

输出格式

The output structure is the one in

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. Adapt as needed, but keep the confidence separation intact, and keep Sources Consulted as one line per investigator, including the ones that returned nothing or were skipped, with the reason.

After the Sources Consulted block, if the user's

why

question is a precursor to actually changing this code, convert the lineage findings into a Preserve / Change / Avoid / Risk constraint set suitable for planning the change.

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）”中每名调查者占一行，包括返回空结果或被跳过的调查者，并注明原因。

在“已查阅来源（Sources Consulted）”部分之后，如果用户的

why

问题是实际修改代码的前置步骤，请将决策沿革发现转换为适合规划变更的保留 / 变更 / 避免 / 风险（Preserve / Change / Avoid / Risk）约束集。

Common Failure Modes to Avoid

需要避免的常见失败模式

Recency bias. Assuming the most recent commit is authoritative. The current shape is often the accretion of many earlier decisions. Trace back.

近因偏差。假定最近的 commit 权威无误。当前形态往往是许多早期决策逐步叠加的结果。持续向前追溯。

Reference Files

参考文件

```
references/epistemics.md
```
. Confidence tiers and phrasing guide. The synthesizer must follow it.
```
references/investigator-prompt.md
```
. Base prompt template for investigator subagents.
```
references/source-playbook.md
```
. Index pointing at the category playbooks below.
```
references/sources/*.md
```
. One self-contained example playbook per category, plus cross-cutting
```
incident-postmortem.md
```
. Give an investigator the single file that matches its category and adapt it to the available MCP.
```
references/synthesizer-prompt.md
```
. Prompt template for the synthesizer subagent, including the output format.

```
references/epistemics.md
```
。置信度层级与措辞指南。synthesizer 必须遵循。
```
references/investigator-prompt.md
```
。调查者 subagent 的基础 prompt 模板。
```
references/source-playbook.md
```
。指向下列各类别 playbook 的索引。
```
references/sources/*.md
```
。每个类别一个自包含的示例 playbook，另加跨领域的
```
incident-postmortem.md
```
。为调查者提供与其类别匹配的那个文件，并根据可用 MCP 进行调整。
```
references/synthesizer-prompt.md
```
。synthesizer subagent 的 prompt 模板，包含输出格式。