| name | investigate |
| description | 構造化されたバグ調査・デバッグワークフロー。デバッグログの挿入による実行時情報の収集、仮説駆動の原因特定、試行ログの自動生成を行う。Trigger - "動かない", "バグ", "エラー", "原因調査", "investigate", "debug", "なぜ失敗する" |
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: エージェント選択の判断に連携
Gotchas
<!-- post-mortem agent appends entries here -->
<!-- Format: - [HASH8] [YYYY-MM-DD] : (hits: N, source: T-XXXX) -->
