Investigate — 構造化デバッグ

デバッグログを武器に、推測ではなく事実に基づいて根本原因を特定する。

Usage

/investigate                    # 直近のエラーから調査開始
/investigate auth token expire  # 特定の問題を調査

$ARGUMENTS で調査対象を指定。省略時は直近のエラー出力やユーザーの症状報告から開始。

Workflow

1. 症状の記録

問題を1文で定義する。曖昧なまま調査を始めない。

## Investigation: [問題の1文要約]
- 症状: [何が起きているか]
- 期待動作: [何が起きるべきか]
- 再現条件: [いつ発生するか]

情報が不足している場合は、AskUserQuestion で確認する。 推測で埋めない。

確認すべき典型的な不足情報:

• 再現手順（「どの画面で」「何をしたら」「何が起きたか」）
• エラーメッセージの全文（スクショではなくテキストが望ましい）
• 最後に正常動作していた時期（直近の変更が原因か切り分け）
• 環境情報（OS、デバイス、ビルドモード等、必要な場合）

2. 情報収集（並列）

以下を並列で実行:

• エラーログ・スタックトレースの確認
• 関連ファイルの特定（Grep/Glob）
• 直近の変更確認（git log -10 --oneline, git diff）

3. デバッグログの挿入

コードを読むだけでは原因がわからない場合、推測する前にデバッグログを入れて実行する。

挿入方針

何がわからない?
    │
    ├─ そもそも到達しているか不明 ──► 通過確認ログ
    ├─ 値が想定と違う可能性 ────────► 変数ダンプログ
    ├─ 条件分岐のどちらに入るか不明 ► 分岐トレースログ
    └─ 処理の順序・タイミングが不明 ► タイムスタンプ付きログ

言語別のログ挿入パターン

言語	ログ手法	プレフィックス
Dart/Flutter	debugPrint()	[DEBUG-INVESTIGATE]
Swift	print() or os_log	[DEBUG-INVESTIGATE]
TypeScript/JS	console.log()	[DEBUG-INVESTIGATE]
Python	print() or logging.debug()	[DEBUG-INVESTIGATE]

プレフィックスは必ず付ける — 後で一括削除するため。

挿入のルール

• 最小限の箇所に入れる — 疑わしいパス全体ではなく、最も可能性の高い箇所から
• 実行して出力を読む — ログを入れたら必ず実行してコンソール出力を確認する
• 出力から絞り込む — 1回目のログで範囲を絞り、必要なら2回目でさらに深掘り
• 最大2ラウンド — 2回のログ挿入→実行で原因が絞れない場合は仮説に切り替え

4. 仮説を立てる

情報収集とデバッグログの結果から仮説を3つ立てる。最も可能性が高い順に並べる。

### 仮説
1. [最有力] 〇〇が原因 — 根拠: [ログ出力/証拠]
2. [次点] △△が原因 — 根拠: [ログ出力/証拠]
3. [可能性低] □□が原因 — 根拠: [ログ出力/証拠]

仮説なしにコードを変更してはならない。 ログ出力という事実に基づかない仮説は弱い。可能なら必ずログで裏取りする。

ログ出力が不明瞭、またはユーザーの症状と仮説が噛み合わない場合は、AskUserQuestion でユーザーに追加情報を求める。 例:

• 「ログ上は正常に見えますが、画面上ではどのような表示になっていますか？」
• 「この操作は毎回失敗しますか、それとも特定の条件で起きますか？」

5. 仮説を検証 → 修正

仮説1から順に検証する。各試行を記録する:

### 試行1: [仮説の要約]
- 根拠: [デバッグログで得た事実]
- 変更: [何をどのファイルで変えたか]
- 検証: [実行したコマンドと結果]
- 結果: ✅ 解決 / ❌ 未解決（理由: ...）

6. 収束判定

試行結果?
    │
    ├─ ✅ 解決 ──────► デバッグログを削除 → 修正サマリーを報告。終了
    ├─ ❌ 試行3回未満 ─► 次の仮説へ（Step 5 に戻る）
    └─ ❌ 3回失敗 ────► STOP → 試行ログをユーザーに提示し判断を仰ぐ

7. クリーンアップ

解決後、デバッグログを必ず全て削除する。

プレフィックスで一括検索して漏れがないことを確認する。デバッグログをコミットしてはならない。

8. 行き詰まり時の報告

3回失敗した場合、ユーザーに報告する:

## 調査行き詰まり報告

3回の試行で解決に至りませんでした。

### デバッグログで判明した事実
- [ログから得られた確定情報]

### 試行履歴
1. [アプローチ] → [結果]
2. [アプローチ] → [結果]
3. [アプローチ] → [結果]

### 共通の失敗パターン
[なぜ全てダメだったかの分析]

### 提案
- [別のアプローチ案]

原則

• わからないことはユーザーに聞く — AskUserQuestion で確認。推測で穴を埋めない
• 推測する前にログを入れる — コードの静的解読だけで原因を決めつけない
• 仮説なしに修正しない — 当てずっぽうの修正はループの元
• 1試行1変更 — 複数の変更を同時にしない（原因が特定できなくなる）
• 検証コマンドを必ず実行 — 「直ったはず」で終わらせない
• デバッグログは必ず消す — DEBUG-INVESTIGATE プレフィックスで一括検索・削除

Integration

• complex-orchestrator: 調査範囲が広い場合、情報収集を並列サブエージェントに委任
• delegation-triggers: エージェント選択の判断に連携