why

Why

コードの背後にある動機と意図を調査します。

how スキルを補完するものです。how はコードが何をし、どのように動作するかを説明します。why は、その形に至った要因を説明します。

以下の各起動では、pstack-models.mdc ルール内の役割の行とデフォルト値を指定します。model にはその行の値を設定し、ルールまたは行がない場合はデフォルト値を設定します。値が auto または inherit-parent の場合は、model を未設定のままにします。Task ツールがスラッグを受け付けない場合は、デフォルト値を使用し、その旨を伝えます。デフォルト値も受け付けられない場合は、エラーメッセージに記載された同じファミリーの最も近い有効なスラッグを使用します。

Operating Posture

慎重で、用心深く、正確な調査者として行動してください。把握していることと推測していることを正直に区別してください。信頼度の枠組みと表現方法の完全なガイドについては、references/epistemics.md を読んでください。統合担当者はこれに従う必要があります。

Step 1. Understand the Target and the Question

ユーザーが何を尋ねているかを把握します。対象は通常、コードの一部、パターン、機能、または名前の付いた設計上の判断です。質問は通常、設計上の根拠、トレードオフ、動機となったエッジケース、外部制約、デッドコード、または広範な履歴の調査です。

対象が曖昧な場合（明確な参照先のない「なぜこの方法を使うのか？」など）は、会話の文脈（開いているファイル、最近の編集、カーソル位置、直前に話し合った内容）から最善の推測を行います。解釈を簡潔に伝え、誤っていればユーザーが訂正できるようにしてから、調査を進めます。

Step 2. Establish the Code Anchor

調査担当者を起動する前に、具体的なコードを調査の基点として特定します。必要な情報は次のとおりです。

• 関連するファイルパスと行範囲
• 主なシンボル（関数名、クラス名、定数）
• 初期コミットの一覧。対象に触れた直近のコミット
• マージコミットに含まれる 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）としてまとめ、調査担当者に渡します。

Step 3. Spawn Parallel Investigators (default posture)

標準では、並列調査をすべて実施してください。

ディスカバリー

調査担当者を起動する前に、Cursor 環境で利用可能な MCP を一覧表示します。利用可能なツールのマップがある場合は、それを使用します。ない場合は、Cursor が公開している mcps/ ディレクトリを調べ、有効な MCP サーバーを確認します。

利用可能な各 MCP を、次のいずれかの証拠カテゴリに分類します。

1. ソース管理履歴
2. イシュー／チケットトラッカー
3. 長文ドキュメント
4. リアルタイムのチームチャット
5. インフラストラクチャの可観測性
6. エラー／例外トラッキング
7. プロダクト分析データウェアハウス

ソース管理は git と gh を通じて常に利用できます。残りの6つについては、MCP 名、サーバーの指示、ツール名、リソースの記述子を使って分類します。複数のカテゴリに該当する可能性がある MCP は、主要な証拠に合致するカテゴリを選びます。曖昧なケースはカバレッジマップに記録します。

最小限のマップではなく、完全なカバレッジマップを目指します。該当するものがない場合も記録し、検索を省略しないでください。

該当する調査担当者は全員、1つのメッセージで起動し、並行して実行します。1人のエージェントに複数の MCP を担当させないでください。

サブエージェントの設定（各エージェント）：

• subagent_type: generalPurpose
• model: why investigators の行。指定がない場合は grok-4.7-xhigh-fast
• readonly: false（エージェントモード）。readonly／Ask モードは使用しないでください。 このモードでは MCP アクセスが取り除かれ、MCP を使う調査担当者が完全に無効になります。調査担当者は引き続き、何も書き込まないでください。

各調査担当者には次の内容を渡します。

1. references/investigator-prompt.md の基本プロンプト
2. 選択した MCP 向けに、references/source-playbook.md の例をもとに調整したカテゴリ別プレイブック references/sources/<source>.md
3. 対象コードが防御的な実装に見える場合は、横断的な references/sources/incident-postmortem.md（null チェック、再試行ロジック、タイムアウト処理、レート制限、機能フラグ、egress ガード、OOM ハンドラー）
4. ステップ2のコードアンカー（ファイルパス、シンボル、コミットハッシュ、PR 番号、チケット ID）
5. ユーザーの元の質問

調査担当者の一覧。利用可能な証拠カテゴリごとに1名

対応する MCP があるカテゴリごとに、調査担当者を1名立ち上げます。それぞれが担当するツールまたは MCP は1つだけです。

各項目にはカテゴリと、そのカテゴリならではの「なぜ」を明らかにする情報の種類を記載します。何が返ってくるか、カテゴリから何も得られなかったときに不足をどう説明するか、そして（まれに、関連性がないと証明できる場合に限り）調査を省略する理由を明確にするために使ってください。

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 ブロック、null ガード、型チェック、再試行など、さまざまな防御処理の調査に特に有効です。

7. プロダクト分析ウェアハウスの調査担当者（Databricks、Snowflake、BigQuery、ClickHouse、dbt、Redshift MCP など）。プロダクト／データの観点から調べます。コードの形に影響を与えたプロダクトやデータの実態を明らかにするのが最も得意です。フラグで制御されるコード、実験に基づくリリース、データ移行、「この数値の出どころは？」といった疑問の調査に特に有効です。

調査担当者を省略する場合

省略できるのは、最終的な「Sources Consulted」セクションに明示的かつ文書で説明できる理由を記載する場合に限ります。認められる理由は2つです。

• この環境では、そのカテゴリに対応する MCP を利用できない。そのカテゴリは選択の結果ではなく、調査できない情報源として記載してください。例：「リアルタイムチームチャットの調査は省略しました。対応する MCP が利用できないため、会話の記録を検索できませんでした。」
• 情報源に関連性がないと証明できる場合。「おそらく関連性がない」だけでは不十分です。高い基準を満たす必要があります。例：「エラー／例外トラッキングの調査は省略しました。対象はビルド時に実行されるスクリプトであり、実行時のコードパスがありません。」

調査範囲の評価から、対象が単一コミットの単純な変更で、PR の説明にすでに完全な回答が記載されていると判断できる場合は、利用可能な7カテゴリすべての調査が冗長であることを確認した後に限り、インラインで回答してもかまいません。そのことを明示してください。この対応はまれであるべきです。

Step 4. 統合する

統合担当のサブエージェントを1つ立ち上げます。

• subagent_type: generalPurpose
• model: why synthesizer の行に記載されたもの。既定値は claude-opus-5-5-max
• readonly: false（エージェントモード）。統合担当は引用を抜き取り確認して品質を検証します。この確認には MCP へのアクセスが必要になる場合があります。読み取り専用／質問モードでは MCP が取り除かれるため、この確認ができません。

統合担当には、次の情報を渡します。

1. 調査担当者の調査結果。該当なしの結果、および理由を付けて省略したカテゴリも含めます
2. Step 2 で特定したコードの根拠（ファイルパス、シンボル、コミットハッシュ、PR 番号、チケット ID）
3. ユーザーの元の質問
4. references/epistemics.md に記載された認識論の枠組み
5. references/synthesizer-prompt.md の統合担当用プロンプトテンプレート

Step 5. 提示する

統合担当の出力をユーザーに提示します。わかりやすさのための軽微な編集や、会話の文脈に基づく補足は可能ですが、確信度を示す表現は書き換えないでください。

出力形式

出力の構成はreferences/synthesizer-prompt.mdに記載されています。「質問」「対象のコード」「確認できたこと」「妥当に推測できること」「競合する仮説」「不明な点」「参照した情報源」「確信度の概要」の順です。必要に応じて調整できますが、確信度の区分は維持してください。また、「参照した情報源」は調査担当者ごとに1行で記載し、情報が得られなかった場合や調査をスキップした場合も、その理由を含めてください。

「参照した情報源」のブロックの後で、ユーザーの「なぜ」という質問が実際にこのコードを変更する前段階にあたる場合は、系譜に関する調査結果を、変更計画に使える「維持／変更／回避／リスク」の制約セットにまとめてください。

よくある失敗パターンとその回避方法

• 直近の変更に偏ること。最新のコミットが正しい根拠だと思い込まないでください。現在の状態は、それ以前の多くの判断が積み重なった結果であることがよくあります。過去までさかのぼって調査してください。

参照ファイル

• references/epistemics.md。確信度の段階と表現に関するガイドです。統合担当はこれに従う必要があります。
• references/investigator-prompt.md。調査担当のサブエージェント向け基本プロンプトのテンプレートです。
• references/source-playbook.md。カテゴリー別プレイブックへのインデックスです。
• references/sources/*.md。カテゴリーごとに独立したサンプルプレイブックと、分野横断的なincident-postmortem.mdがあります。該当カテゴリーの単一ファイルを調査担当に渡し、利用可能なMCPに合わせて調整してください。
• references/synthesizer-prompt.md。統合担当のサブエージェント向けプロンプトテンプレートです。出力形式も含まれています。