Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

how 的伴侣。how 回答代码做什么、怎么工作。why 回答什么力量塑成了它的形状。

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。综合者必须遵守。

Step 1. Understand the Target and the Question

Step 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.

目标含糊（「我们为什么这样做？」没有清晰指称）时，从对话上下文（打开的文件、近期编辑、光标位置、刚讨论的）做最佳猜测。简短陈述你的理解，让用户偏了能纠正，然后继续。

Step 2. Establish the Code Anchor

Step 2. 建立代码锚点

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

spawn investigator 前，把调查锚定在具体代码。你需要：

  • 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)

  • 相关文件路径与行范围

  • 关键符号（函数名、类名、常量）

  • 初始 commit 列表：最近碰目标的几条

  • 合并 commit 里的 PR 号（主题行里的 (#1234) 模式）

Build this inline.

内联建这些。

用 git blame / log 锚定目标（示例命令保持英文）：

# 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:

对实质性 commit，用 gh 拉 PR 正文与讨论：

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.

抓成种子上下文（文件路径、符号、commit、PR 号、关联工单 ID）。传给 investigator。

Step 3. Spawn Parallel Investigators (default posture)

Step 3. Spawn 并行 investigator（默认姿态）

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.

spawn investigator 前，从 Cursor 环境列出可用 MCP。有 available-tools 图就用。否则检查 Cursor 暴露的 mcps/ 目录里已启用 MCP 服务器。

Map each available MCP to one evidence category:

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

  1. Source control history

  2. Issue / ticket tracker

  3. Long-form documents

  4. Real-time team chat

  5. Infrastructure observability

  6. Error / exception tracking

  7. Product analytics warehouse

  8. 源控历史

  9. Issue / 工单 tracker

  10. 长文文档

  11. 实时团队聊天

  12. 基础设施可观测性

  13. 错误 / 异常追踪

  14. 产品分析仓库

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.

源控始终经 git 和 gh 可用。其余六个用 MCP 名、服务器说明、工具名、资源描述符分类。一个 MCP 可进多类时，选匹配其主要证据的那类。含糊情况记入覆盖图。

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.

在一条消息里启动全部匹配的 investigator，让它们并发。别让一个 agent 覆盖多个 MCP。

Subagent config (each):

每个 subagent 配置：

  • subagent_type: generalPurpose

  • model: your configured why-investigators model (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.

  • subagent_type: generalPurpose

  • model: 配置的 why-investigators 模型（默认 grok-4.7-xhigh-fast）

  • readonly: false（agent 模式）。不要用只读/Ask 模式。 它剥掉 MCP 访问，MCP 支持的 investigator 会整组失效。investigator 仍不该写任何东西。

Each investigator gets:

每个 investigator 拿到：

  1. The base prompt from references/investigator-prompt.md

  2. The category playbook references/sources/<source>.md for the selected MCP, adapted from the examples in references/source-playbook.md

  3. 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)

  4. The code anchor from Step 2 (file paths, symbols, commit hashes, PR numbers, ticket IDs)

  5. The user’s original question

  6. references/investigator-prompt.md 的基础 prompt

  7. 所选 MCP 的类别 playbook references/sources/<source>.md，从 references/source-playbook.md 示例适配

  8. 若目标代码看起来防御性（null 检查、重试、超时、限流、feature flag、egress 守卫、OOM 处理），加横切的 references/sources/incident-postmortem.md

  9. Step 2 的代码锚点（文件路径、符号、commit 哈希、PR 号、工单 ID）

  10. 用户原始问题

Investigator roster. One per available evidence category

Investigator 名册。每个可用证据类别一个

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

有匹配 MCP 的每个类别 spawn 一个 investigator。每个恰好拥有一个工具或 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.

每条点名类别及其独特浮出的「为什么」。用来知道期望什么回来、类别空时如何命名缺口，以及（仅在罕见可证无关情况下）为跳过辩护。

  1. 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.

  2. 源控 investigator。Git 历史、gh 拉 PR、代码注释、测试。始终 spawn。唯一有保证的源。最擅浮出审阅时捕获的实现期理由。

  3. 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.

  4. Issue / 工单 tracker investigator（如 Linear、Jira、GitHub Issues、Plane、Shortcut MCP）。最擅浮出产品或业务强制函数。为什么在工程外部时最强。

  5. 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.

  6. 长文文档 investigator（如 Notion、Confluence、Google Docs、Coda MCP）。最擅浮出长文设计理由。为什么在变成代码前写出来的地方。

  7. 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.

  8. 实时团队聊天 investigator（如 Slack、Discord、Microsoft Teams、Mattermost MCP）。最擅浮出从未进文档的实时审议。源控、工单、文档纸迹薄时尤其重要。

  9. 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).

  10. 基础设施可观测性 investigator（如 Datadog、New Relic、Honeycomb、Grafana、Splunk MCP）。基础设施/运行时视角。最擅浮出驱动代码的基础设施与运行时现实。目标对基础设施信号反应时最强（超时、重试、限流、断路器）。

  11. 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.

  12. 错误 / 异常追踪 investigator（如 Sentry、Rollbar、Bugsnag、Airbrake MCP）。最擅浮出驱动防御或纠正代码的具体异常与错误轨迹。catch、null 守卫、类型检查、重试及其他防御最强。

  13. 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.

  14. 产品分析仓库 investigator（如 Databricks、Snowflake、BigQuery、ClickHouse、dbt、Redshift MCP）。产品/数据视角。最擅浮出塑成代码的产品与数据现实。flag 门控代码、实验驱动合入、数据迁移、「这数字从哪来」类问题最强。

When to skip an investigator

何时跳过 investigator

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

只有带着最终 “Sources Consulted” 小节里的明确书面理由才跳过。两个合法理由：

  • 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.”

  • 本环境该类别没有可用 MCP。 标成缺口，不是选择。例：“Real-time team chat skipped. No matching MCP available, so the conversational record was not searchable.”

  • 源可证明无关，不只是「大概无关」。门槛高。例：“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.

若范围评估显示单 commit 琐碎目标、PR 描述已含完整答案，只有在确认全部七类可用搜索都会冗余后，才可内联回答。明确说出来。这应很少见。

Step 4. Synthesize

Step 4. 综合

Spawn one synthesizer subagent:

Spawn 一个 synthesizer subagent：

  • subagent_type: generalPurpose

  • model: your configured why-synthesizer model (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.

  • subagent_type: generalPurpose

  • model: 配置的 why-synthesizer 模型（默认 claude-opus-5-5-max）

  • readonly: false（agent 模式）。综合者质检抽查引用，可能需要 MCP。只读/Ask 模式剥掉 MCP，会破坏这一点。

The synthesizer gets:

综合者拿到：

  1. The investigator findings, including any null results and any categories skipped with justification

  2. The code anchor from Step 2 (file paths, symbols, commit hashes, PR numbers, ticket IDs)

  3. The user’s original question

  4. The epistemics framework from references/epistemics.md

  5. The synthesizer prompt template from references/synthesizer-prompt.md

  6. investigator 发现，含空结果与带理由跳过的类别

  7. Step 2 的代码锚点

  8. 用户原始问题

  9. references/epistemics.md 的认识论框架

  10. references/synthesizer-prompt.md 的综合者 prompt 模板

Step 5. Present

Step 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.

拿综合者输出交给用户。可为清晰轻度编辑或加对话上下文，但不要改写置信度用语。

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.

输出结构见 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 每个 investigator 一行，含空手或跳过的，并附理由。

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.

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。置信档与措辞指南。综合者必须遵守。

  • references/investigator-prompt.md。investigator subagent 的基础 prompt 模板。

  • references/source-playbook.md。指向下面类别 playbook 的索引。

  • references/sources/*.md。每类一份自含示例 playbook，加横切 incident-postmortem.md。给 investigator 匹配其类别的单文件，并适配可用 MCP。

  • references/synthesizer-prompt.md。综合者 subagent 的 prompt 模板，含输出格式。