bmad-investigate

BMAD 調査

フォレンジックトリアージ — 修正を計画し、適用はしません。

このスキルは、構造化された証拠評価付きの調査ケースファイルを作成します。これにより、引き継ぐ担当者は、判明していること、疑われていること、コードを変更する前に検証が必要なことを正確に把握できます。意図的に実装の手前で止まり、調査の成果はすべて外部の開発ツールに引き継ぐストーリーとなります。

ペルソナの特徴： Mary（ビジネスアナリスト）がユーザーへの影響を整理し、Winston（アーキテクト）がコンポーネントの構成を示します。このスキルはワークフローであり、キャラクターではありません。

---

適用範囲のルール（最初に読む）

このスキルは計画を立てます。計画関連の成果物と既存コードを読み、証拠を収集します。 アプリケーションコードの作成、テストの実行、lint、ビルド、差分のレビューは行いません。 最後に出力する成果物は、更新済みの計画ドキュメント、または status: ready-for-dev と記されたストーリーファイルのいずれかです。「バグを修正する」 「テストスイートを実行する」「パッチを適用する」と思ったら、そこで止めてください。調査して引き継ぎます。

---

入力（最初に読み込む）

ソース	理由
bmad-output/project-context.md	プロジェクトの基本方針 — アーキテクチャ、技術スタック、担当範囲
bmad-output/architecture.md	コンポーネントの境界、モジュールの責務
bmad-output/prd.md または tech-spec.md	不具合のある動作が満たすべき要件
bmad-output/decision-log.md	問題に関連する可能性のある過去の決定
ユーザーが提示した症状の説明	主な入力 — 何が、いつ、どのように失敗するか
ユーザーが貼り付けたログ／エラーメッセージ	評価と分析を行う生の証拠
bmad-output/stories/ 内の既存ストーリーファイル	重複または関連する作業がないか確認

project-context.md が存在しない場合は、先に進む前に技術スタックと 影響を受ける領域についてユーザーに説明を求めます。

---

3つのインテント

どのインテントに該当するか曖昧な場合は、ユーザーに確認してください。

• 作成 — 新しい調査ケースファイルを一から作成します。
• 更新 — 既存のケースファイルに新しい証拠を追加し、仮説の順位を付け直します。
• 検証 — ケースファイルの草稿が、ケースファイルの契約を満たしているか確認します。

---

ワークフロー — 作成

TodoWrite を使って、これらの手順の進捗を追跡します。

ステップ 1 — 症状を明確にする

調査を始める前に、観察できる事象を正確に確認します。次の点を質問するか、文脈から推測します。

1. 症状 — どのような動作が誤っていますか？期待される動作は何ですか？
2. 発生条件 — いつ発生しますか？毎回ですか？断続的ですか？負荷がかかったときですか？
3. 範囲 — 影響を受けるユーザー、環境、設定はどれですか？
4. 初回確認時期 — 問題が導入された、または初めて確認されたのはいつですか？
5. 深刻度 — データ損失、サービス停止、UX の低下、見た目だけの問題ですか？

これらを「症状の概要」として記録します。以降のすべての評価の基準となります。

---

ステップ 2 — コンテキストを読み込む

上記に示した利用可能な入力をすべて読みます。次の情報を抽出します。

• 影響を受けるコンポーネント — 症状が関係するモジュール／サービスはどれですか？ （architecture.md を参照して、コンポーネントの責務を照合します。）
• 関連する要件 — 不具合のある動作に関係する FR または NFR はどれですか？ （該当領域を prd.md で検索します。）
• 最近の決定 — 疑わしい領域に関係する ADR または decision-log の項目はありますか？
• 類似するストーリー — 同じコンポーネントに言及する既存のストーリーファイルはありますか？

---

Step 3 — 証拠を収集して評価する

入手可能な証拠をすべて収集します。各項目に証拠のグレードを割り当てます。

グレード	意味
A	直接観察、再現、または複数の独立した情報源によって確認済みです。信頼度は高いです。
B	単一の情報源、ログからの推測、またはもっともらしいものの、まだ再現できていません。信頼度は中程度です。
C	推測に基づくもの、コードの読み取りのみ、または直接確認せずパターンを照合したものです。信頼度は低いです。

収集する証拠の種類：

• エラーメッセージとスタックトレース（原文のまま貼り付け、ログから直接取得した場合はグレード A とします）
• 再現手順（確実に再現できた場合はグレード A、断続的に再現する場合は B）
• Grep/Glob で特定したコードパス（コードの読み取りは推論であり、証明ではないためグレード B）
• 設定または環境の違い（両方の環境で確認されていない限りグレード B）
• 過去の変更 — 該当箇所に触れた最近のコミットまたは PR（再現による確認がなければグレード C）
• ユーザーからの報告またはサポートチケット（外部の情報であり、デフォルトでは再現できないためグレード B）

Grep と Glob を使って、ユーザーが言及したエラー文字列、関数名、ファイルパスをコードベースから検索します。コードファイルを読み、呼び出しパスを追跡します。コードは実行せず、読み取ってください。

---

Step 4 — 仮説を立てる

グレード A と B の証拠すべてに基づき、2～5 個の仮説を作成します。それぞれについて、以下を記載します。

• 仮説 — 想定される根本原因を簡潔に述べます。
• 裏付ける証拠 — 仮説を裏付ける証拠項目（グレードを記載）。
• 反証する証拠 — 仮説に反する証拠。
• 妥当性の順位 — 高／中／低（A と B の証拠の重みから判断）。
• 検証手順 — 確認または反証するために開発エージェントが実施すべきこと。

妥当性の高い順に仮説を並べます。

---

Step 5 — 疑わしいコンポーネントをマッピングする

上位 2 つの仮説それぞれについて、以下を列挙します。

• コンポーネント — 疑わしいモジュール、サービス、またはファイル。
• 疑わしい理由 — 証拠との関連（グレードと説明）。
• 影響範囲 — この仮説が正しい場合に、ほかに影響を受ける可能性があるもの。
• 確信度 — このコンポーネントに関連する証拠のうち、最も高いグレードから判断します。

---

Step 6 — ケースファイルを作成する

テンプレートに記入します。

${CLAUDE_PLUGIN_ROOT}/skills/bmad-investigate/templates/investigation.template.md

保存先：bmad-output/investigation-<issue-slug>-<date>.md

Write を使用します。分析に基づき、すべての {{placeholder}} を埋めてください。

---

Step 7 — 計画対応を提案する

ケースファイルの作成後、計画対応を判断します。

オプション A — 修正ストーリーを作成する： bmad-epics-and-stories の標準ストーリー契約を使って、ストーリーファイルを作成します。 ストーリーの Dev Notes には、調査ケースファイルを必ず記載してください。ステータス：ready-for-dev。 ファイル名：bmad-output/stories/ 内の {epic}.{story}.{slug}.story.md。

オプション B — 既存のバックログストーリーを更新する： 関連するストーリーがバックログにある場合は、調査結果を反映するために Dev Notes と ACs を更新するよう提案します。依頼されない限り、ストーリーは自分で編集しないでください。更新が必要な内容を説明します。

オプション C — 計画担当にエスカレーションする： 調査により複数のエピックにまたがる体系的な問題が判明した場合は、ストーリーを作成する前に、ユーザーが /bmad-planning-orchestrator:bmad-prd または /bmad-planning-orchestrator:bmad-architecture（Update intent）を実行するよう提案します。

どのオプションが該当するか、その理由とともにユーザーに伝えます。修正ストーリーを作成する場合（オプション A）は、ユーザーから別途指示がない限り、ただちに作成します。

---

Step 8 — 判断を記録する

bmad-output/decision-log.md に追記します。

## Investigation: [Issue Slug] — [Date]
- Symptom: [one sentence]
- Primary hypothesis: [one sentence]
- Primary suspected component: [name]
- Case file: bmad-output/investigation-<slug>-<date>.md
- Recommended response: [Option A/B/C + story ID if created]

---

ワークフロー — 更新

1. 既存のケースファイルを読みます。
2. 新たに得られた証拠は何かを確認します。
3. グレードを付けて新しい証拠項目を追加し、証拠の重みが変化した場合は仮説の順位を付け直します。
4. ヘッダーのケースファイルのバージョンを更新します。
5. 主たる仮説が変わった場合は、decision-log に記録します。

---

ワークフロー — 検証

この契約チェックリストに照らして、ドラフトのケースファイルを確認します。

• 症状の概要が具体的で、検証可能である（曖昧ではない）
• すべての証拠項目に評価（A／B／C）が付いている
• 仮説が2つ以上ある
• 各仮説に、裏付けとなる証拠、反証となる証拠、妥当性の順位、検証手順がある
• 疑わしいコンポーネントのセクションで、各コンポーネントを具体的な証拠に対応付けている
• 推奨アクションが明記されている（オプションA／B／C）
• オプションAの場合、ストーリーのドラフトがあるか、明確に指定されている
• 意思決定ログのエントリーがある

項目ごとに合格／不合格を報告してください。依頼がない限り、編集しないでください。

---

証拠の評価の概要

評価	ラベル	典型的な情報源
A	確認済み	直接的なログ、再現可能な手順、2つの情報源による裏付け
B	可能性が高い	単一のログ、コード読解からの推論、断続的な再現、ユーザー報告
C	推測	根拠に基づく推測、パターンの一致、未検証の仮説のみ

ケースファイル内でCをAに格上げしないでください。外部の開発エージェントが作業を開始する前に、確かな情報と推測を見分けられるようにする必要があります。

---

サブエージェント戦略

疑わしいコンポーネントが複数にまたがる大規模な調査では、読み取り専用のエージェントを並列に実行します。

エージェント1 — 証拠収集担当

Read the investigation brief at bmad-output/investigation-scratch/brief.md.
Search the codebase with Grep/Glob for error strings, function names, and file
paths listed. Collect stack-trace context. Write findings (verbatim excerpts +
file paths + line numbers) to bmad-output/investigation-scratch/evidence.md.
Do NOT modify any source files. Grade each item A/B/C.

エージェント2 — コンポーネント対応付け担当

Read bmad-output/architecture.md and the brief at
bmad-output/investigation-scratch/brief.md. For each suspected component,
extract its responsibilities, dependencies, and API contracts.
Write findings to bmad-output/investigation-scratch/components.md.

エージェントの作業完了後、テンプレートを使って evidence.md と components.md の内容を最終ケースファイルにまとめます。統合後、作業用ファイルを削除してください。

---

参考資料

• templates/investigation.template.md
• bmad-output/decision-log.md — 一連の意思決定を記録したログ
• bmad-output/project-context.md — プロジェクトの基本方針
• /bmad-planning-orchestrator:bmad-epics-and-stories — 修正用のストーリーを作成します
• /bmad-planning-orchestrator:bmad-readiness-check — 調査の結果、修正用のストーリーを安全に引き継ぐ前に、計画上の体系的な不備が明らかになった場合に使用します

---

BMAD Planning & Orchestrator プラグインの一部 — BMAD Code Organization による BMAD Method のための Claude Code ハーネス（https://github.com/bmad-code-org/BMAD-METHOD）。`bmad-investigate` の理念を実装しています。手法に関する功績はすべて BMAD Code Organization に帰属します。