bmad-investigate

調査

概要

入手可能な証拠から、何が起きているのか、またはなじみのない領域が何をするのかを再構成します。別のエンジニアが事前知識なしで引き継げる、構造化されたケースファイルを作成します。欠陥追跡（症状駆動型）と領域探索（症状なし）の間で継続的に調整します。どちらの端でも同じ規律が適用されます。

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

出力: {implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename}。参照入力は記録されます。生の内容は、成果がそれを必要とするまで親コンテキストに読み込まれません。

{slug} は、チケット ID が提供されている場合はそのチケット ID、そうでない場合はユーザーと合意した短い説明的な名前で、小文字の英数字とハイフンに正規化されます。解決されたパスに既存のケースファイルと衝突する場合は、slug-YYYY-MM-DD.md に名前を変更するか、既存のファイルを再開するかを尋ねます（再開すると成果 0 にルーティングされます）。

各成果の後、判明したことを提示し、続行する前にユーザーのために一時停止します。

原則

• 証拠の格付け。
  • 確認済み。 直接観察されたもの。path:line、ログのタイムスタンプ、またはコミットハッシュを引用します。
  • 推論済み。 確認済みの証拠から論理的に導かれるもの。連鎖を示します。
  • 仮説。 もっともらしいが未確認のもの。何がそれを確認または反証するかを述べます。
• まず堅牢な足場。 確認済みの証拠を 1 つ選んで固定し、そこから外側へ広げます。決して理論から始めて裏付けを探してはいけません。証拠が乏しい場合は、証拠が少ないモードに切り替えます（成果 1 の分岐）。
• 前提に異議を唱える。 ユーザーの説明は仮説であり、事実ではありません。独立して検証します。証拠が矛盾する場合は、その旨を述べます。
• 物語ではなく証拠に従う。 証拠が作業中の理論と矛盾する場合は、理論を更新します — 決してその逆ではありません。ユーザーが確信している場合でも、確証バイアスに抗います。
• 仮説は決して削除されません。 ステータス（Open / Confirmed / Refuted）を更新し、解決を追加します。回り道も成果物の一部です。
• 証拠の欠如自体が発見です。 そのギャップ、それが何を解決するか、そしてそれをどのように入手するかを文書化します。
• 早めに書き留める。 slug が合意されたらすぐにケースファイルを初期化します。これは中断をまたぐ永続的な状態です。
• path:line の引用は CWD 相対形式を使用し、先頭に / を付けません。これにより IDE 埋め込みターミナルでクリック可能になります。
• 委任の規律。 ステップで 5 つ以上のファイル、または 10K トークンを超えるファイルを読む必要がある場合は、構造化された JSON のみを返すサブエージェントに委任します。結果から path:line を引用します。親で再読み込みしないでください。
• 独立した操作を並行して発行する（マルチ grep、マルチ読み込み、並列インベントリ）— 1 つのメッセージ、複数のツール呼び出し。
• コミュニケーション。 証拠を優先する言葉遣い（「証拠が示すのは」「未確認、検証には X が必要」）。曖昧な表現や物語は禁止。

起動時

ステップ 1: ワークフローブロックを解決する

実行: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow

スクリプトが失敗した場合は、停止してエラーを表面化します。

ステップ 2: prepend ステップを実行する

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

ステップ 3: 永続的な事実を読み込む

{workflow.persistent_facts} の各エントリを基礎的なコンテキストとして扱います。file: プレフィックスは {project-root} 配下のパスまたは glob です（内容を読み込みます）。その他のエントリはそのままの事実です。

ステップ 4: 設定を読み込む

{project-root}/_bmad/bmm/config.yaml を読み込み、{user_name}、{communication_language}、{document_output_language}、{implementation_artifacts}、{project_knowledge} を解決します。{implementation_artifacts} が未解決の場合は、./investigations/ にフォールバックし、初期化する前にフォールバックを表面化します。

ステップ 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 つの発見です。エビデンスインベントリと調査 バックログを更新します。上記の要約とともにユーザーのために一時停止し、指示を待ちます。

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

• 因果関係をたどる。 症状駆動型: 症状から逆方向にたどり、それを生み出した条件と発生した状態を明らかにします。探索型: 出力 (戻り値、副作用、送信されたメッセージ) から逆方向にたどり、それを生み出した条件を明らかにします。同じ手法で、起点が異なります。
• タイムラインを再構築する。 ログ、システムイベント、バージョン管理、ユーザーの観察を相互参照して行います。
• 仮説を立て、検証する。 明示し、裏付ける証拠・反証する証拠を特定し、調査し、格付けする (確定 / 反証済み / 未決)。ステータスを更新します。決して削除しないでください。
• 反証パス。 仮説が確定に向かって遷移するたびに、まず反証する証拠を積極的に探します。その試みを Resolution に記録します。
• ユーザーの前提を検証する。 証拠が矛盾する場合は、その旨を明示します。
• 発見したパスをバックログに追加する。 現在のスレッドに集中し続けます。

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

成果 4: 重要な箇所でソースをたどった

これらの初回パスのスキャンを、1 つのメッセージ内で並列のツール呼び出しとして発行します。正確なエラー文字列を grep する、影響を受けるディレクトリで並列実装を glob する、git log で最近の変更を確認する。

次に順番に: 周辺のコードを読む、呼び出し元の連鎖をたどる、言語とプロセスの境界の越境 (コンパイル済み→スクリプト、IPC、ホスト→デバイス、構成フロー) に注意する。

ケースタイプ別に絞り込みます:

• 探索型: I/O マッピング (トリガー、出力、依存関係)、頻出語スキャン、制御フローのフィルタリング (分岐、ループ、エラー処理、状態機械の遷移)。
• 症状駆動型: 深さの評価 — 根本原因はローカルなコンテキストから到達可能か、それともより広範なエリアモデルが必要か? エスカレーションを表面化させ、決して黙ってスコープを広げないでください。些細な修正の評価 — off-by-one、null チェックの欠落、引数の入れ替え → レポートに 1 行のコード提案またはドラフトの diff を記載、些細でない場合 → 根本原因の領域で停止します。

調査は診断で停止し、実装はスコープ外です。Source Code Trace (エラーの発生源、トリガー、条件、関連ファイル、より広範な場合はエリアモデル) を更新します。上記の要約とともにユーザーのために一時停止し、指示を待ちます。

成果 5: レポートが確定し、引き継ぎがクリーンである

{case_file} を更新します:

• Hand-off Brief を最終形に書き換える (3 文、15 秒で読める)。
• Final Conclusion を信頼度付きで: High (根本原因が確定、再現が決定的)、Medium (推論済み、軽微な不確実性)、Low (仮説、明確なデータギャップ)。
• Fix direction を該当する場合に記載 (複数が組み合わさる場合はメカニズム別に分類)。
• Diagnostic steps を不確実性が残る場合に記載。
• Reproduction Plan を該当する場合、または探索型ケース用の検証計画を記載。
• Status: Active / Concluded / Blocked on evidence。

結論を提示し、次に具体的な次のステップのメニューを提示します: 些細な修正 → bmad-quick-dev、スコープ・計画の調整 → bmad-correct-course、追跡するストーリー → bmad-create-story、新規レビュー → bmad-code-review。最も価値の高いアクションを推奨します。緩和策と回避策は明示的な要求があった場合にのみ生成されます — 調査は診断で停止します。{workflow.on_complete} が空でない場合は実行します。上記の要約とともにユーザーのために一時停止し、指示を待ちます。

フォローアップのイテレーション

新しい ## Follow-up: {YYYY-MM-DD} ブロックの下に {case_file} へ追記して作業を続けます (同日の再エントリーでは #2、#3)。調査は次の場合に完了します:

• 根本原因が確定している。
• 根本原因が仮説であり、明確なデータギャップがある。
• メンタルモデルがユーザーの述べた目標に対して十分である (探索型ケース)。
• バックログに、入手できない証拠を必要とする項目のみが含まれている。
• ユーザーが明示的に結論を下す。