why

理由

Codex では、このスキルを実行する前に、スキルごとのメモも含めてプラットフォームマッピングを読んでください。

GitHub Copilot では、このスキルを実行する前に、スキルごとのメモも含めてプラットフォームマッピングを読んでください。

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

how スキルと対になるスキルです。how はコードが何をするのか、どのように動くのかに答えます。why は、どのような力が働いてその形になったのかに答えます。

以下の各起動では、pstack-models.md 内のロール行と、Models のデフォルト値を指定しています。model には、その行の値を設定してください。シートまたは行がない場合は、デフォルト値を設定します。値が auto または inherit-parent の場合は、model を未設定のままにしてください。Agent ツールがスラッグを受け付けない場合は、デフォルト値を使い、その旨を伝えてください。デフォルト値も受け付けない場合は、エラーメッセージに示された同じファミリーの有効なスラッグのうち、最も近いものを使ってください。

運用姿勢

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

ステップ 1. 対象と質問を把握する

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

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

ステップ 2. コードの基点を確立する

調査担当者を起動する前に、調査対象を具体的なコードに結び付けてください。必要な情報は次のとおりです。

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

ステップ 3. 並行して調査担当者を起動する（デフォルトの進め方）

デフォルトでは、並行調査をすべて実施してください。

検出

調査担当者を起動する前に、Claude Code 環境で利用可能な MCP を一覧表示します。システムプロンプトの先頭にあるツール一覧を使用してください（各 MCP は mcp__<server>__<name> というプレフィックスのツールとして表示されます）。それ以外の場合は、プラグイン／プロジェクト内の .mcp.json を読むか、claude mcp list を実行してください。

利用可能な各 MCP を、次の証拠カテゴリのいずれかに割り当てます。

1. ソース管理の履歴
2. Issue／チケットトラッカー
3. 長文ドキュメント
4. リアルタイムのチームチャット
5. インフラストラクチャのオブザーバビリティ
6. エラー／例外トラッキング
7. プロダクト分析ウェアハウス

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

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

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

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

• subagent_type：general-purpose
• model：why investigators の行に記載されたモデル。Models のデフォルトを使用します
• readonly：false（エージェントモード）。readonly／Ask モードは使用しないでください。 MCP へのアクセスが無効になり、MCP を利用する調査担当者が機能しなくなります。調査担当者は、引き続き何も書き込まないでください。

各調査担当者に渡す内容：

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

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

一致する MCP があるカテゴリごとに、調査担当者を1名起動します。各担当者は、ちょうど1つのツールまたは MCP を担当します。

各エントリには、カテゴリ名と、そのカテゴリだけが明らかにできる「なぜ」の種類が記載されています。これは、何が返ってくることを期待すべきか、カテゴリが空を返したときにギャップをどう名付けるか、そして（証明可能なほど無関係な稀なケースに限り）スキップを正当化するために使用します。

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）。プロダクト / データの視点です。コードを形作ったプロダクトとデータの現実を明らかにするのが最も得意です。フラグで制御されたコード、実験主導のリリース、データ移行、「この数値はどこから来たのか」という問いに最も強力です。

調査担当者をスキップする場合

スキップするのは、最終的な「参照したソース」セクションに記載する明示的で書面による正当化がある場合だけです。有効な理由は2つです:

• この環境にそのカテゴリで利用可能な MCP がない場合。これは選択ではなくギャップとしてフラグを立てます。例: 「リアルタイムチームチャットはスキップ。一致する MCP が利用できないため、会話の記録は検索できませんでした。」
• そのソースが証明可能なほど無関係であり、単に「おそらく無関係」ではない場合。これは高いハードルです。例: 「エラー / 例外トラッキングはスキップ。対象はランタイムのコードパスを持たないビルド時スクリプトです。」

スコープ評価により、PR の説明にすでに完全な答えが含まれている単一コミットの些細な対象が示唆される場合、7つすべての利用可能なカテゴリ検索が冗長であることを確認した後にのみ、インラインで回答してもかまいません。その旨を明示的に述べてください。これは稀であるべきです。

ステップ4. 統合

1つの統合サブエージェントを起動します:

• subagent_type: general-purpose
• model: why synthesizer の行、デフォルトは Models にあります
• readonly: false（エージェントモード）。統合担当者の品質チェックは引用をスポット検証しますが、これには MCP アクセスが必要になる場合があります。readonly / Ask モードは MCP を剥奪し、それを妨げます。

統合担当者が受け取るもの:

1. 調査担当者の調査結果（null の結果や、正当化とともにスキップされたカテゴリを含む）
2. ステップ2のコードアンカー（ファイルパス、シンボル、コミットハッシュ、PR 番号、チケット ID）
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 は調査員ごとに 1 行とし、何も返さなかったものやスキップされたものも理由とともに含めてください。

Sources Consulted ブロックの後に、ユーザーの why の問いが実際にこのコードを変更することの前触れである場合は、系譜の調査結果を、変更を計画するのに適した Preserve / Change / Avoid / Risk の制約セットに変換してください。

避けるべき一般的な失敗モード

• 直近性バイアス。最新のコミットが権威的であると仮定すること。現在の形は、多くの場合、それ以前の多数の決定が積み重なったものです。さかのぼって追跡してください。

参照ファイル

• references/epistemics.md。信頼度の階層と表現のガイド。シンセサイザーはこれに従わなければなりません。
• references/investigator-prompt.md。調査員サブエージェント用の基本プロンプトテンプレート。
• references/source-playbook.md。以下のカテゴリ別プレイブックを指すインデックス。
• references/sources/*.md。カテゴリごとに 1 つの自己完結したプレイブックの例、および横断的な incident-postmortem.md。調査員には、そのカテゴリに一致する単一のファイルを渡し、利用可能な MCP に適応させてください。
• references/synthesizer-prompt.md。出力形式を含む、シンセサイザーサブエージェント用のプロンプトテンプレート。

モデル

ロールのデフォルトは、plugins/pstack/models.json からスタンプされます（そこを編集し、tools/generate.mjs を再実行してください）。pstack-models.md オーバーライドシート内の一致するロール行が、実行時にそれぞれを上書きします。/setup-pstack がそれを作成し、ランタイムごとにそのパスを一覧表示します。

• why 調査員: opus
• why シンセサイザー: opus

推論エフォート

オーバーライドシート内のロールの値は、そのモデルの後に推論エフォートを指定できます。たとえば opus @xhigh のようにです。Claude Code でのレベル: low、medium、high、xhigh、max。どれが適用されるかはモデルによって異なります。@ のない値は、シートの default effort 行、レベル、または session を取ります。シートにそのような行がない場合は session です。session はエフォートを設定しないため、ディスパッチは通常どおりです。モデルを読み取る前に接尾辞を除去してください。inherit-parent または auto は、どのレベルでも依然として model を省略し、モデル名は model として渡されます。Claude Code では、レベルは、そうでなければ使用する subagent_type からエフォートエージェントを選びます。pstack:poteto-agent は subagent_type: "pstack:poteto-agent-<level>" になります。general-purpose、または subagent_type なしは、subagent_type: "pstack:effort-<level>" になります。エフォートエージェントは effort のみを設定するため、渡すモデルが依然としてモデルを決定します。Codex では、レベルを spawn_agent の reasoning_effort として渡し、通常の指示を保ってください。