# 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: ファイル読み込みのアプローチ比較

```js
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: エラー連発時のリセット

```js
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 を呼ぶ必要は無い (オーバーヘッドになる)