maestro/docs/tools/brainstorm.md

Brainstorm 詳細ガイド

着手前または行き詰まり時に、複数アプローチを構造化された形で比較してから 1 つを採用する 思考の checkpoint ツール。

LLM が「最初に思いついた方法でそのまま突き進む」「同じ tool が失敗してるのに同じ args で呼び直す」といったループに陥ることを防ぐ。

何を解決するか

問題のあるパターン:

失敗 → リトライ → 失敗 → リトライ → 失敗 → リトライ → ...

Brainstorm を挟むと:

失敗 → Brainstorm({ context: 失敗内容, approaches: [A, B, C], chosen: B }) → B を試す

必須フィールド

フィールド	説明
task	今解こうとしているサブ問題を 1 文 で。例: "input/data.xlsx の中身を要約したい"
approaches	検討する解法の配列。2 個以上必要 (1 個だと比較にならない)
chosen	採用する approach の name。approaches[].name のどれかと完全一致させる
rationale	採用理由を 1-2 文で

任意フィールド

フィールド	説明
context	これまで試した手段・失敗内容など。行き詰まり時のリセット用途で記入する

approaches[] の各要素

フィールド	必須	説明
name	✓	短い名前 (例: "ReadExcel 直接", "CSV エクスポート経由")
description	✓	1-2 文で具体的な手順
reliability	-	high / medium / low。副作用無し・後戻り可能なら high
speed	-	fast / medium / slow
prerequisites	-	前提条件・必要なもの
risks	-	想定される失敗パターン

使うべき場面

1. 複雑な依頼の着手前 — レポート生成・複数ファイル処理・多段階の調査など
2. 同じ tool が 2 回以上失敗した時 — エラー内容を context に書いて、別アプローチを 2-3 個並べる
3. 存在しないファイルを掴んだ時 — output/foo.xlsx が無いと分かった時点で「Glob で実在確認 / ユーザーに ASK / 別パスを試す」を比較
4. 方針が複数あって迷った時 — どっちでも動きそうな選択肢がある時に、確実性で選び直す

使わなくて良い場面

• 短い質問への即答
• 自明な単一 tool で済む依頼 (例: 「current time を教えて」)
• 1-2 ステップで完結する操作

使い方の例

例1: ファイル読み込みのアプローチ比較

Brainstorm({
  task: "input/data.xlsx の中身を要約したい",
  approaches: [
    {
      name: "ReadExcel 直接",
      description: "ReadExcel({ path: 'input/data.xlsx' }) で全シート読む",
      reliability: "high",
      speed: "fast",
    },
    {
      name: "シート分割→個別 Read",
      description: "SplitExcelSheets で .md に分割してから Read で 1 シートずつ",
      reliability: "high",
      speed: "medium",
      prerequisites: "出力ディレクトリの書き込み許可",
    },
    {
      name: "ヘッダーだけ先に確認",
      description: "ReadExcel に range: 'A1:Z3' を渡して構造把握 → 範囲拡大",
      reliability: "high",
      speed: "fast",
      risks: "範囲を間違えるとデータを取り逃がす",
    },
  ],
  chosen: "ReadExcel 直接",
  rationale: "ファイルサイズが小さければ全件読みが最速で確実"
})

例2: エラー連発時のリセット

Brainstorm({
  task: "output/レポート.xlsx を読みたい",
  context: "ReadExcel が JSZip エラー、ReadPdf も extension mismatch、Bash cat も file not found。\n直前のターンで Write が成功したという認識だが実際は失敗していた可能性",
  approaches: [
    {
      name: "Glob で実在確認",
      description: "Glob({ pattern: 'output/*' }) で実際に存在するファイル一覧を取る",
      reliability: "high",
      speed: "fast",
    },
    {
      name: "Write をやり直す",
      description: "前回の Write 失敗が原因なら、対象ファイルを改めて生成する",
      reliability: "medium",
      speed: "medium",
      risks: "既存ファイルを上書きしてしまう可能性",
    },
    {
      name: "ユーザーに ASK",
      description: "complete({ status: 'needs_user_input', missing_info: 'ファイルパスを確認させて' })",
      reliability: "high",
      speed: "slow",
    },
  ],
  chosen: "Glob で実在確認",
  rationale: "副作用なしで現状把握できる。実在しないなら次の手も決まる"
})

出力の形

Brainstorm は以下のような Markdown を返す:

# Brainstorm: <task>

## 背景 / これまでの試行
<context があれば>

## 検討した N 個のアプローチ

  **A 案**
    <description>
    [確実性: high / 速度: fast]

✓ **B 案** (採用)
    <description>
    [確実性: medium / 速度: medium]

  **C 案**
    ...

## 採用: B 案
理由: <rationale>

続けて、採用したアプローチで実装に進んでください。

このアウトプットが activity log / tool 履歴に残るので、後から「どのアプローチを比較したか」「なぜそれを選んだか」を追跡できる。

注意

• Brainstorm は思考の checkpoint であって、独立した解答ではない。Brainstorm 後は採用したアプローチで実際の tool を呼ぶ
• 2 個以上の approaches が必須。1 個だと「比較」にならない
• chosen は approaches[].name と完全一致必要 (大小・空白も含めて)
• 短い質問・自明なタスクで Brainstorm を呼ぶ必要は無い (オーバーヘッドになる)