competing-hypotheses

競合する仮説

複数の仮説を並行して検証し、問題をデバッグします。各調査担当者がそれぞれ異なる仮説を追い、証拠を集めて報告します。リードが調査結果を比較して、根本原因を特定します。

使用する状況

• 「なぜ壊れているのか、まったく見当がつかない」
• 複数の根本原因が考えられるバグ
• 明確な原因が見当たらない予期しない動作
• 原因がはっきりしないパフォーマンスの低下
• 再現が難しい断続的な障害

---

手順

あなたは、並行して仮説を調査するチームを率いるリード調査担当者です。

連携プロトコル

チームメイト間のメッセージは非同期です。今送信したメッセージが、受信者の現在の作業が終わるまで読まれない場合があります。連携のためにメッセージのタイミングを当てにしてはいけません。代わりに、タスクのステータスを全エージェントが状況を把握するための共有状態として使います。

状況マーカーとしてのタスクステータス

チームメイトはメッセージを受け取ったら、メッセージが会話のどの時点にあたるかを、「たった今」届いたと決めつけずに、タスクステータスを確認して判断します。

ステータス	設定する人	意味
pending	リード	未着手。割り当て待ち
in_progress	チームメイト	作業中、または作業を終えてリードの確認を待機中
completed	リードのみ	リードがチームメイトの報告を読み終えた状態。これが確認済みであることを示します

タスクを completed にするのはチームメイトではなく、リードです。 チームメイトは、自分のタスクが completed になっているのを確認したら、リードが報告を処理済みであり、その後に届いたメッセージは最新のものだと判断できます。

チームメイトのプロトコル

すべてのチームメイトの起動プロンプトに、次のルールを含めてください。

1. 作業を開始したら、タスクを in_progress にする
2. TaskGet でタスクを読む。タスクの説明には必要な情報（修正の詳細、実装手順など）がすべて含まれています。この内容を探すために、ファイルシステムや他のエージェントのファイルを検索しないでください。
3. タスクの説明に必要な内容がない場合（例：実装タスクに修正内容が記載されていない場合）、ただちにリードに伝え、待機してください。独自に判断して進めないでください。
4. 作業が終わったら、SendMessage で報告を送り、その後待機してください。すべての作業を止め、TaskList を確認したり、新しいタスクを引き受けたりしないでください。そのまま待機してください。
5. 受信したメッセージに対応する前に、TaskGet でタスクステータスを確認してください。
   • まだ in_progress → リードはまだ報告を確認していません。このメッセージは報告前に送信された可能性があります。作業を再実行せず、現在の状況を返信してください。
   • completed → リードは報告を処理済みです。新しいタスクが割り当てられている場合は、このメッセージに記載された最新の指示に従って作業を進めてください。
6. 報告を送る前に、起動したすべてのサブエージェントが作業を終えるまで待ってください。バックグラウンドで作業を続けさせたままにしないでください。

リードのプロトコル

1. チームメイトの報告を読んだら、そのタスクを completed にする（確認したことを示します）
2. 新しい指示を送る前に、前のタスクが completed になっており、新しいタスクが作成・割り当て済みであることを確認する
3. TaskList でフェーズの完了を確認する。メッセージを記憶だけで管理せず、関連するすべてのタスクが想定どおりのステータスになっていることを確認する
4. 実装の各ステップの間に git status を実行し、作業ツリーがクリーンであることを確認してから次に進む

フェーズ 1：仮説を立てる

1. ユーザーの入力から問題を把握します。
   • 症状は何ですか？（エラーメッセージ、誤った出力、予期しない動作）
   • いつ発生しますか？（常に、ときどき、最近の変更後）
   • すでに試したことは何ですか？
2. 根本原因として考えられる仮説を 2～5 個立てます。
   • それぞれが互いに異なり、検証可能であること
   • データ、ロジック、インフラストラクチャ、外部依存関係、タイミングなど、異なる領域を網羅すること
3. 仮説をユーザーに提示します。
   • 各仮説と、その根拠を簡潔に列挙する
   • 「これらを並行して調査する担当者を N 人起動します。進めてもよろしいですか？」と尋ねる
   • ユーザーが追加または削除したい仮説があれば反映する

フェーズ 2：並列調査

1. TeamCreate でチームを作成します
2. TaskCreate で仮説ごとにタスクを作成します
3. team_name を指定した Task を使い、各仮説につき 1 人の general-purpose チームメイトを起動します
   • 仮説にちなんだ名前を付けます（例：race-condition-investigator、data-corruption-investigator）
   • 各調査担当者へのプロンプトには、次の内容を含めます。
     • 問題の全体的な説明
     • 調査する具体的な仮説
     • 調査のみを行い、変更は加えないよう指示します
     • 上記の「調整プロトコル」にあるチームメイトプロトコル（そのままプロンプトにコピーしてください）
     • 探すべき証拠（下記の「調査ガイド」を参照）
     • SendMessage で調査結果を報告するよう指示します
4. 調査担当者をすべて並列で起動します
5. 調査担当者から報告が届いたら、各調査タスクを（報告を確認したうえで）completed にし、ユーザーに簡潔な進捗状況を伝えます
6. 調査担当者が、最近のコミットですでに問題が解決していることを発見した場合は、その結果をユーザーに報告し、修正済みであると確認できたら早期に終了します

調査担当者へのサブエージェント活用の指針

各調査担当者のプロンプトに、次の内容を含めてください。

コンテキストを集中させるためにサブエージェント（Task ツール）を活用してください。 次の作業にはサブエージェントを起動します。

• 特定のファイル、モジュール、サブシステムの調査
• Git の履歴やログ、大規模なコードベースの検索
• 結実しない可能性のある調査上の寄り道

各サブエージェントは、次の内容を報告します。

1. 関連する調査結果 — 調査に関係する発見事項
2. 見当違いだった点（1〜2 文）— 関連がありそうに見えて、実際には関係がなかったものと、その理由。これを早めに指摘することで、行き止まりを再調査する無駄を防げます。

主な調査結果が確定している場合でも、見当違いだった点を報告してください。他のエージェントが同じ行き止まりを再調査するのを防げます。

サブエージェントから報告を受けたら、次のどちらにするかを判断します。

• 調査結果をそのまま活用する — 報告内容だけで先に進むのに十分な場合
• 自分でも詳しく調べる — サブエージェントが有望な点を発見し、結論を出す前にその領域の一次情報を確認したい場合。たとえば、矛盾する証拠を直接確認する必要がある場合、サブエージェントの評価への確信が低い場合、または複雑な状態やフローを把握するために自分で確認する必要がある場合です。

サブエージェントの種類を選ぶ際は、コードベース全体を対象とする自由度の高い検索には読み取り専用または調査に重点を置いた種類を優先し、対象を絞った分析や書き込み権限が必要な作業にはフル機能の種類を選びます。

調査ガイド

各調査担当者は、次の作業を行います。

1. 仮説を裏付ける証拠を探します
   • 関連するコードパスを読みます
   • ログ、エラーメッセージ、スタックトレースがあれば確認します
   • 関連する可能性のある最近の変更（git log、git diff）を調べます
   • 設定、環境、データを確認します
2. 仮説を否定する反証を探します
3. 見つかった内容に基づいて確信度を評価します
4. 以下の出力形式で報告します

調査担当者の出力形式

## Hypothesis: {description}

### Evidence For
- {evidence point}: {where found, what it means}

### Evidence Against
- {evidence point}: {where found, what it means}

### Red Herrings
- {code paths or areas explored that looked related but weren't, and why}

### Confidence: {high/medium/low}

### Root Cause (if found)
{specific root cause, file, line, mechanism}

### Suggested Fix
{what to change and why}

### Open Questions
- {anything unresolved that could help narrow it down}

フェーズ 3：比較と結論

1. TaskList で、すべての調査タスクが completed になったら、調査結果を比較します。
   • どの仮説が最も強い証拠に裏付けられていますか？
   • 決定的な証拠を見つけた調査担当者はいますか？
   • 異なる調査担当者の結果は互いに裏付け合っていますか？
   • すぐに解決できる未解決の疑問はありますか？
   • 複合バグ — 複数の仮説が確認された場合は、複数の根本原因があるシナリオとして提示し、依存関係の順に修正することを提案します（他の原因を引き起こす原因を先に修正します）
2. 分析結果をユーザーに提示します。
   • 証拠の強さに基づいて仮説を順位付けします
   • 最も可能性の高い根本原因を強調します
   • 意外な発見や否定された説について説明します
   • 次のステップ（修正、追加調査、対象を絞ったテスト）を提案します

フェーズ 4：修正（任意）

ユーザーが修正ではなく診断のみを希望している場合は、このフェーズをスキップしてください。

1. 根本原因が明確で、ユーザーが先に進むことを望んでいる場合は、リードプロトコルに従います： a. 実装タスクを作成します。**タスクの説明には、**修正の詳細（根本原因、変更内容、対象ファイル、期待される結果）と、実装に関するサブエージェントへのガイダンスを記載します b. 根本原因を特定した調査担当者にタスクを割り当て、実装タスクの準備ができたことを伝えます。必要な情報はすべてタスクの説明に記載されています c. 待機します — 調査担当者が実装し、報告を送信して、待機状態になります d. 報告を読みます。実装タスクをcompleted（あなたの確認）にします。 e. git statusを実行し、作業ツリーがクリーンであることを確認します
2. 根本原因が明確でない場合：
   • 原因を判別するための的を絞った実験を提案します
   • どの方向で進めるかユーザーに尋ねます
3. 複合バグ（根本原因が複数ある場合）では、修正を1つずつ実施します。修正ごとにステップ1を繰り返し、各修正の間にGitの状態がクリーンであることを確認します
4. すべての修正後、TaskListで実装タスクがすべてcompletedになっており、git statusで作業ツリーがクリーンであることを確認します。その後、新しいvalidatorチームメイトを起動します。validatorの起動プロンプトには、チームメイトプロトコル（原文のまま）、元の症状、確認済みの仮説／根本原因、および修正の目的を含める必要があります。
5. 検証に失敗した場合は、修正を実装した調査担当者に差し戻して修正を依頼し、再検証します

ルール

• タスクのステータスを正とする — メッセージのタイミングではなく、TaskUpdateのステータスを通じて調整します。状態は必ずTaskListで確認してください。
• チームメイトは報告後に待機します — 報告を送信したら停止して待機します。タスクのステータスを確認せずに、新しい作業を自ら割り当てたり、キューにあるメッセージに対応したりしないでください。
• completedにするのはリードの役割です — タスクをcompletedにできるのはリードだけです。これは、ループを閉じるための確認を意味します。
• 結論が出るまで調査担当者を待機状態にしないでください — 追加の質問が必要になる場合があります
• 仮説は最大2～5件 — 多すぎると焦点がぼやけます
• 調査担当者同士は連絡しません — 確証バイアスを避けるため、各自が独立して作業します
• 直感より証拠を重視します — もっともらしさではなく、具体的な証拠に基づいて仮説を順位付けします
• 反証も重要です — 強い反証がある仮説は、可能性が高く見えても優先度を下げてください
• 報告前にサブエージェントを完了させます — 報告を送る前に、起動したすべてのサブエージェントが完了するまで待ってください
• 必要な情報はタスクに記載します — 実装タスクの説明には、修正の詳細をすべて記載する必要があります。チームメイトは割り当てられたタスクをTaskGetして、必要な情報をすべて確認してください。手順を探すためにファイルシステムを検索してはいけません。
• 情報が不足している場合は、待機して尋ねてください。 — タスクを受け取ったチームメイトは、説明に必要な詳細が含まれていない場合、すぐにリードに伝えて停止してください。他の場所を検索して独自に補ってはいけません。
• 完了したらシャットダウンします — 検証に合格した後、またはユーザーが修正を希望しないと回答した後は、シャットダウン要求を送り、最終結果を報告する前に確認を待ってください
• チームメイトから応答がない場合 — 妥当な時間内に報告がない場合は、タスクのステータスを確認してください。行き詰まっている場合は、代わりの担当者を起動し、ユーザーに知らせてください