--- name: why description: "用于‘X 为何这样工作’、‘我们为何选择 Y’、设计理由、回归、事后分析或数据支持阈值。发现可用 MCP,并并行查询每个证据类别(源代码管理、issue 跟踪器、长篇文档、实时聊天、基础设施观测、错误跟踪、产品分析仓库),然后返回带引用的决策与权衡解读。运行行为请使用 how。” disable-model-invocation: true --- # Why(为何) 调查代码背后的动机与意图。配套 `how` 技能回答代码做什么及如何工作。`why` 回答哪些力量塑造了它的形态。 下面每次生成都对应 `pstack-models.mdc` 规则中的一个角色行和一个默认值。将 `model` 设为该行的值;规则或行缺失则使用默认值。值为 `auto` 或 `inherit-parent` 时不要设置 `model`。若 Task 工具拒绝某个 slug,使用默认值并说明。若它拒绝默认值,则从错误消息中使用同系列最接近的有效 slug。根据 **poteto-mode** 技能的 Subagents 部分,为每项工作选择子代理推理级别及快速或标准速度。 每次生成都使用 `generalPurpose` 和 `readonly: false`(代理模式)。**不要使用 readonly/Ask 模式。**那会剥离 MCP 访问,禁用由 MCP 支持的调查者及综合器的引用抽查。调查者仍不应写入任何内容。 ## 工作姿态 以**谨慎、缜密、精确的调查者**身份工作。诚实区分你知道与推断的内容。阅读 `references/epistemics.md` 了解完整置信框架与措辞指南。综合器必须遵循。 ## 步骤 1:理解目标与问题 **目标**通常是代码块、模式、功能或具名设计决策。**问题**通常是设计理由、权衡、促成修改的边界情况、外部约束、死代码或广泛历史扫描。 若目标含糊(“我们为什么这样做?”但没有明确所指),根据对话上下文作出最佳推测(打开的文件、最近编辑、光标位置、刚讨论的内容)。简要说明解释,以便你偏离时用户能纠正,然后继续。 ## 步骤 2:建立代码锚点 生成调查者前,就地建立种子上下文:文件路径和行范围、关键符号(函数、类、常量)、触及目标的最近提交、合并提交中的 PR 编号(主题行中 `(#1234)` 模式)及任何关联工单 ID。运行 `git blame -L , ` 查最近触及,运行 `git log --follow -p -- ` 通过重命名获取完整历史及补丁,运行 `git log --oneline -20 -- ` 查含 PR 编号的近期提交,运行 `git log -1 --format=%B ` 提取 PR 编号。然后为任何实质性提交拉取 PR 正文和讨论:`gh pr view --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews`。该锚点发送给每位调查者与综合器。 ## 步骤 3:并行生成调查者 **默认进行完整并行调查。**目标是完整覆盖图,而非最小图。记录空结果,不要跳过搜索。 ### 发现 生成调查者前,从 Cursor 环境列出可用 MCP。存在可用工具映射时使用它。否则检查 Cursor 为已启用 MCP 服务器公开的 `mcps/` 目录。 将每个可用 MCP 映射到一个证据类别: 1. 源代码管理历史 2. Issue/工单跟踪器 3. 长篇文档 4. 实时团队聊天 5. 基础设施观测 6. 错误/异常跟踪 7. 产品分析仓库 源代码管理始终可通过 git 与 `gh` 使用。其余六类根据 MCP 名称、服务器说明、工具名称和资源描述分类。若 MCP 适合多个类别,选择与其主要证据相符的一类。在覆盖图中记录歧义情形。 每个有匹配 MCP 的类别生成一位调查者,全部放在一条消息中以并发运行;每位只负责一个工具或 MCP。不要让一个代理覆盖多个 MCP。`model`:`why investigators` 行,默认 `grok-4.7-xhigh-fast`。 每位调查者的提示词由 `references/investigator-prompt.md` 填写,再加上: - 所选 MCP 的类别行动手册 `references/sources/.md`,根据 `references/source-playbook.md` 的示例调整 - 若目标代码看起来具有防御性(空值检查、重试逻辑、超时处理、限流、功能开关、出站防护、OOM 处理),则加 `references/sources/incident-postmortem.md` - 代码锚点和用户的原始问题 ### 调查者名单,每个可用证据类别一位 下列每个类别都独特地揭示一种“为何”,列在“最擅长”之后。用它了解预期回报、在类别返回空时命名缺口,并仅在很少出现且可证明无关的情况下说明跳过理由。 1. **源代码管理**(git 历史、用于 PR 的 `gh`、代码注释、测试)。始终生成,这是唯一受保证的来源。最擅长*审查期间记录的实现期理由*。 2. **Issue/工单跟踪器**(例如 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` 行,默认 `claude-opus-5-5-xhigh`。它获得: 1. 调查者发现,包括所有空结果及有理由跳过的类别 2. 代码锚点 3. 用户原始问题 4. `references/epistemics.md` 中的认识论框架 5. `references/synthesizer-prompt.md` 中的综合器提示词模板 ## 步骤 5:呈现 向用户呈现综合器输出。可为清晰稍作编辑或从对话添加上下文,但**不要改写置信措辞**。 ## 输出格式 结构采用 `references/synthesizer-prompt.md`:问题、问题中的代码、我们发现、可合理推断、竞争假设、尚不知道、已查阅来源、置信摘要。可按需调整,但保持置信区分,并让 Sources Consulted 每位调查者一行,包括返回空或跳过的调查者及原因。 Sources Consulted 后,若用户的 `why` 问题是修改此代码的前奏,将谱系发现转化为用于规划改动的 Preserve / Change / Avoid / Risk 约束集。 ## 应避免的常见失败模式 - **近因偏差**。假定最近提交最有权威。当前形状常是许多早期决策累积的结果。要追溯。