gds-investigate

調査

概要

利用可能な証拠から、何が起きているのか、または不慣れな領域がどのような役割を果たすのかを再構築します。別のエンジニアが予備知識なしで引き継げる、構造化されたケースファイルを作成します。欠陥の追跡（症状主導）と領域の調査（症状なし）の間を継続的に調整します。どちらの場合も、同じ規律を適用します。

引数： チケット ID、ログファイルのパス、診断アーカイブ、エラーメッセージ、コード領域名、問題の説明、または既存のケースファイルへのパス。最後の形式は以前の調査を再開し、それ以外は新しいケースを開始します。

出力： {implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename}。参照入力を記録します。結果によって必要になるまでは、元の内容を親コンテキストに読み込みません。

{slug} は、チケット ID が指定されている場合はその ID、それ以外の場合はユーザーと合意した短い説明的な名前とし、小文字の英数字とハイフンのみを使用するように整えます。解決後のパスに既存のケースファイルがある場合は、slug-YYYY-MM-DD.md に名前を変更するか、既存ファイルを再開するかを尋ねます（再開する場合は Outcome 0 に進みます）。

各 Outcome の後に、判明した内容を提示し、続行する前にユーザーの確認を待ちます。

原則

• 証拠の評価。
  • 確認済み。 直接観察した内容です。path:line、ログのタイムスタンプ、またはコミットハッシュを引用します。
  • 推論済み。 確認済みの証拠から論理的に導かれる内容です。推論の連鎖を示します。
  • 仮説。 妥当ではあるものの、確認されていない内容です。確認または反証に必要なことを示します。
• 確かな証拠を起点にする。 確認済みの証拠を1つ基点とし、そこから範囲を広げます。理論から始めて、その裏付けを探してはいけません。証拠が乏しい場合は、証拠が限られるモード（Outcome 1 の分岐）に切り替えます。
• 前提を検証する。 ユーザーの説明は仮説であり、事実ではありません。独自に検証し、証拠と矛盾する場合はその旨を伝えます。
• 筋書きではなく証拠に従う。 証拠が作業中の理論と矛盾する場合は、理論を更新します。逆に、理論に合わせて証拠を曲げてはいけません。ユーザーが確信している場合でも、確証バイアスを避けます。
• 仮説を削除しない。 ステータス（Open / Confirmed / Refuted）を更新し、Resolution を追加します。誤った方向に進んだ経緯も成果物の一部です。
• 証拠の欠如も発見事項です。 何が不足しているか、それによって何が解決するか、どうすれば入手できるかを記録します。
• 早めに記録する。 slug が合意されたら、すぐにケースファイルを初期化します。これは中断をまたいで保持される状態です。
• Path:line の引用には、先頭に / を付けない、CWD 相対形式を使用します。IDE に埋め込まれたターミナルでクリックできます。
• 委任の規律。 5つ以上のファイルを読む必要がある場合、または1万トークンを超えるファイルを読む場合は、構造化された JSON のみを返すサブエージェントに委任します。返された結果の path:line を引用し、親コンテキストで再読込しないでください。
• 独立した操作は並行して実行します（複数の grep、複数の読み込み、並行したインベントリ作成など）。1つのメッセージで複数のツール呼び出しを行います。
• コミュニケーション。 証拠を優先した表現（「証拠が示しているのは」「未確認のため、検証には X が必要」）を使います。曖昧な表現や筋書きに沿った説明は避けます。

起動時

Step 1: ワークフローブロックを解決する

実行：uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow

スクリプトが失敗した場合は停止し、エラーを提示します。

Step 2: 前置ステップを実行する

{workflow.activation_steps_prepend} の各項目を順番に実行します。

Step 3: 永続的な事実を読み込む

{workflow.persistent_facts} の各項目を基礎となるコンテキストとして扱います。file: プレフィックスが付いている項目は、{project-root} 配下のパスまたは glob（内容を読み込む）です。それ以外の項目は、そのまま事実として扱います。

Step 4: 設定を読み込む

{project-root}/_bmad/gds/config.yaml を読み込み、{user_name}、{communication_language}、{document_output_language}、{implementation_artifacts}、{project_knowledge} を解決します。{implementation_artifacts} が解決されない場合は ./investigations/ にフォールバックし、初期化する前にフォールバックしたことを伝えます。

Step 5: 挨拶する

{communication_language} で {user_name} に挨拶します。

ステップ 6: 追加ステップを実行する

{workflow.activation_steps_append} の各エントリを順番に実行します。

アクティベーションが完了しました。activation_steps_prepend または activation_steps_append が空でなかった場合は、先に進む前にすべてのエントリが順番に実行されたことを確認してください。すべてのアクティベーションステップが完了するまで、メインワークフローを開始しないでください。

ステップ 7: 確認とルーティング

入力を参照として確認します（パスと ID を記録し、生の内容は読み取りません）。既存のケースファイルへのパス → アウトカム 0。それ以外 → アウトカム 1。

手順

アウトカム 0: 既存のケースが読み込まれ、提示される

ケースファイルを読み取ります。次の順序で提示します: 未解決の仮説（Status = Open）とその確認/反証基準; 未解決の バックログ（Status ≠ Done）; 欠落しているエビデンスの行; 信頼度を含む最後の結論。どのスレッドを掘り下げるか尋ねます。新しい エビデンスは新しい ## Follow-up: {YYYY-MM-DD} ブロックを開きます（同日の再エントリでは #2、#3 を追加）。上記の要約とともにユーザーのために一時停止し、指示を待ちます。

アウトカム 1: スコープと拠り所が確立される

各入力の形状を確認します — 記録するのは場所、スコープ、時間枠のみです。一括読み取りはアウトカム 2 で行います。

• 課題トラッカーのチケット。 利用可能な MCP ツールを介して完全な詳細を取得します。
• 診断アーカイブ。 パス、ファイル数、時間枠を記録します。
• ログファイルまたはスタックトレース。 パスと時間枠を記録します。ここでのスコープは、ユーザーのメッセージにすでに含まれている スタックフレームのみです。
• フリーテキストの説明。 そのまま記録し、仮説として扱います。
• コード領域の名前（症状なし）。エントリポイントを記録します。
• 最近のコミット領域。 コミット範囲を記録します。

ユーザーが仮説を持って到着した場合は、それを仮説 #1 として登録します。拠り所を独立して見つけます。ユーザーの 仮説は、拠り所が検証または反証する対象の 1 つです。

拠り所を見つけます: 確認済みのエビデンス（エラーメッセージ、関数名、HTTP ルート、設定パラメータ、テスト ケース）。ここをアンカーとします。

分岐する前に {case_file} を初期化します。 パスは {implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename} で、{slug} が置換されます（slug および衝突ルールは概要を参照）。{workflow.case_file_template} からファイルを作成し、ハンドオフブリーフ （ラフ）、ケース情報、問題記述、初期エビデンスインベントリを記入します。

エビデンスが乏しい分岐。 確認済みのエビデンスに到達できない場合: ハンドオフ ブリーフでケースをエビデンスが乏しいとマークします。調査バックログに優先順位付けされたデータ収集項目を設定します。「進めるために、次のいずれかが必要です: …」と記録します。ユーザーがエビデンスを提供するか、アウトカム 2 によるより広範なスキャンを承認するまで一時停止します。

それ以外の場合は、スコープ、拠り所、ファイルパス、提案するアプローチを提示します。上記の要約とともにユーザーのために一時停止し、指示を待ちます。

アウトカム 2: エビデンスの範囲がマッピングされる

現場を調査します: これらの独立したカテゴリにわたって利用可能なエビデンスを並行して棚卸しします: 診断アーカイブ; 課題トラッカー; バージョン管理; テスト結果; 静的解析; ソースコード。約 10K トークンを超えるカテゴリについては、 JSON マニフェスト（パス、サイズ、時間枠、path:line として引用された主要な断片）を返すサブエージェントに委任します。

各項目を Available、Partial、Missing に分類します — Missing 自体が 1 つの発見です。エビデンスインベントリと調査 バックログを更新します。上記の要約とともにユーザーのために一時停止し、指示を待ちます。

Outcome 3: 原因を規律をもって推論する

• 因果関係をたどります。 症状主導の場合：症状から、その症状を引き起こした条件と、そこから生じた状態までさかのぼります。探索の場合：出力（戻り値、副作用、送信されたメッセージ）から、それを引き起こした条件までさかのぼります。同じ手法ですが、起点が異なります。
• ログ、システムイベント、バージョン管理、ユーザーの観察内容を相互参照して、時系列を再構成します。
• 仮説を立てて検証します。 仮説を記述し、裏付ける証拠または否定する証拠を特定して、調査し、評価します（Confirmed / Refuted / Open）。Status を更新します。削除はしません。
• 反証の確認を行います。 仮説が Confirmed に近づくたびに、まず反証となる証拠を積極的に探します。その試みを Resolution に記録します。
• ユーザーの前提を検証します。 証拠が前提と矛盾する場合は、明確に伝えます。
• 見つかったパスをバックログに追加します。 現在のスレッドに集中します。

Confirmed Findings、Deduced Conclusions、Hypothesized Paths、Backlog、Timeline を更新します。元の前提と矛盾する点を強調します。上記の要約をユーザーに提示して一時停止し、指示を待ちます。

Outcome 4: 重要な箇所までソースを追跡する

次の初回スキャンを、1つのメッセージで並列のツール呼び出しとして実行します：完全一致するエラー文字列を grep で検索し、影響を受けたディレクトリ内の並行実装を glob で検索し、最近の変更を git log で確認します。

続いて、順番に進めます：周辺のコードを読み、呼び出し元の連鎖をたどり、言語やプロセスの境界を越える箇所（コンパイル済みコード→スクリプト、IPC、ホスト→デバイス、設定の流れ）に注意します。

ケースの種類に応じて、調査の重点を変えます：

• 探索： I/O マッピング（トリガー、出力、依存関係）、頻出用語のスキャン、制御フローの絞り込み（分岐、ループ、エラー処理、ステートマシンの遷移）。
• 症状主導： 深さを評価します。根本原因はローカルなコンテキストから特定できるのか、それともより広範な領域モデルが必要なのかを判断します。調査範囲の拡大が必要な場合は明示し、黙って範囲を広げてはいけません。簡単な修正かどうかも評価します。オフバイワン、null チェックの不足、引数の取り違えの場合は、レポートに1行のコード提案または差分案を記載します。複雑な修正の場合は、根本原因の領域までで止めます。

調査は診断の時点で終了します。実装は対象外です。Source Code Trace（Error origin、Trigger、Condition、Related files。範囲が広い場合は area model も含む）を更新します。上記の要約をユーザーに提示して一時停止し、指示を待ちます。

Outcome 5: レポートを仕上げ、引き継ぎを明確にする

{case_file} を更新します：

• Hand-off Brief を最終版に書き直します（3文、15秒で読める長さ）。
• Final Conclusion に確信度を記載します：High（根本原因を Confirmed、再現は決定的）、Medium（Deduced、わずかな不確実性あり）、Low（Hypothesized、データの不足が明確）。
• 該当する場合は Fix direction を記載します（複数の要因が組み合わさる場合は、メカニズムごとに分類）。
• 不確実性が残る場合は Diagnostic steps を記載します。
• 該当する場合は Reproduction Plan を記載します。探索ケースでは、代わりに検証計画を記載します。
• Status： Active / Concluded / Blocked on evidence。

結論を提示した後、具体的な次のステップの選択肢を示します：簡単な修正 → gds-quick-dev、範囲や計画の調整 → gds-correct-course、追跡対象のストーリー → gds-create-story、新たなレビュー → gds-code-review。最も価値の高いアクションを推奨します。緩和策や回避策を提示するのは、明示的に依頼された場合に限ります。調査は診断の時点で終了します。{workflow.on_complete} が空でない場合は実行します。上記の要約をユーザーに提示して一時停止し、指示を待ちます。

フォローアップの反復

作業を続ける場合は、{case_file} に新しい ## Follow-up: {YYYY-MM-DD} ブロックを追加します（同じ日に再開する場合は #2、#3 を付けます）。次の条件を満たした時点で調査は完了です：

• 根本原因が Confirmed である。
• 根本原因が Hypothesized で、データの不足が明確である。
• ユーザーが明示した目標（探索ケース）を達成できるだけのメンタルモデルが得られている。
• バックログに、入手できない証拠が必要な項目だけが残っている。
• ユーザーが明示的に終了を宣言した。