brainstorm

/brainstorm — 計画の前に目標を明確にする

目的： WHAT と HOW を切り分けます。解決策を決める前に、問題領域を探ります。

ループ内の位置

運用ループの **1（意図を BDD として形にする）**より前の段階です。自由記述の目標を受け取り、/discovery がBDD 意図イシューに取り込める、Given/When/Then 形式の受け入れ例を作成します。以下のフェーズ 4 の「記録」ステップは、少なくとも 1 つの正常系と 1 つの重要なエッジケースを、テスト可能な Gherkin として記述するまで完了しません。「動作するはず」は、記録された例ではありません。

2 つのモード

/brainstorm は 2 つのモードのいずれかで実行されます。これらは相互に補完するものであり、排他的ではありません。セッションをアイデア創出モードで開始し、アイデアを 1 つ選んで、HOW の探索のために目標明確化モードへ移行することもできます。

モード	使用する場面	形式
目標明確化（デフォルト。以下の 4 つのフェーズ）	目標が 1 つの具体的な機能を示している場合（"add JWT auth"、"fix the login bug"）	その目標に対する WHAT を明確にし、HOW を探ります。
アイデア創出（自由形式。アイデア創出モードを参照）	目標が自由形式の場合（"improve the project"、"what should we build next"）、またはフェーズ 1 で単一の目標が浮かび上がらず exploring となった場合、または --ideate が渡された場合	多数の改善案を生成し、徹底的に絞り込み、残った案を具体化します。

完全なモード選択表は、references/ideation-mode.mdにあります。

4 つのフェーズ（目標明確化モード）：

1. 明確さを評価する — 目標は十分に具体的ですか？
2. アイデアを理解する — どのような問題か、誰にメリットがあるか、何が存在しているか？
3. アプローチを探る — 選択肢を生成し、トレードオフを比較し、批判的に検討します。
4. 設計を記録する — /plan 用の構造化された出力を作成します。

---

クイックスタート

/brainstorm "add user authentication"     # full 4-phase process
/brainstorm                                # prompts for goal

---

実行手順

フェーズ 1：明確さを評価する

ユーザーが目標の文字列を指定した場合は、その内容を評価します。指定していない場合は、目標を尋ねます。

明確さを判断する選択肢を提示し、AskUserQuestion を使用します。

• clear — 目標が具体的で、実行可能である（例：「API に JWT 認証を追加する」）
• vague — 目標はあるが、範囲を絞る必要がある（例：「セキュリティを改善する」）
• exploring — まだ確固とした目標はなく、方向性だけがある（例：「認証に関する何か」）

vague または exploring の場合は、先に進む前に目標を明確にするための追加質問をします。具体的な問題の記述（1 文で、テスト可能なもの）ができるまで、フェーズ 2 に進んではいけません。

フェーズ 2：アイデアを理解する

以下の質問に答えます（必要に応じてコードベースを調査します）。

1. どのような問題を解決しますか？ — 具体的な言葉で課題を述べます。
2. 誰にメリットがありますか？ — エンドユーザー、開発者、運用担当者、CI パイプラインのどれですか？
3. 現在、何が存在していますか？ — 現状、コードベース内の先行事例、関連システムを確認します。
4. 重要な制約は何ですか？ — パフォーマンス、互換性、セキュリティ、スケジュールを確認します。

次に進む前に、調査結果を要約します。不明な点があれば、ユーザーに尋ねます。

フェーズ 3：アプローチを探る

異なるアプローチを 2～3 個生成します。それぞれについて、以下を示します。

• 名前 — 短いラベル（例：「JWT ミドルウェア」、「OAuth プロキシ」、「セッション Cookie」）
• 仕組み — 2～3 文で説明します。
• 利点 — うまくできる点
• 欠点 — うまくできない点、または先送りする点
• 工数 — おおまかな範囲（小／中／大）

フェーズ 3b: 敵対的クリティーク

ユーザーに選択を求める前に、各アプローチをストレステストします:

各アプローチについて、以下の レッドチーム質問 に答えてください(references/red-team-checklist.md を参照):

1. 最初に壊れるものは何か? — 負荷、エッジケース、または敵対的入力の下で
2. 隠れたコストは何か? — メンテナンス負担、技術的負債、学習曲線
3. どの前提が間違っているか? — このアプローチを良さそうに見せている、明言されていない信念
4. 誰が反対するか? — 正反対の選好を持つシニアエンジニアなら何と言うか?

レッドチーム質問に 2 つ以上失敗したアプローチは、比較において HIGH RISK とマークしてください。

すべてのアプローチが 2 つ以上の質問に失敗した場合は、弱点に対処する 4 番目の「ハイブリッド」アプローチを生成してください。

比較を提示し、AskUserQuestion を使用して、ユーザーがアプローチを選ぶか、ハイブリッドを要求できるようにします。

フェーズ 4: 設計のキャプチャ

日付スラッグを生成します: YYYY-MM-DD-<goal-slug>(小文字、ハイフン、スペースなし)。

出力ファイルを .agents/brainstorm/YYYY-MM-DD-<slug>.md に書き込みます:

---
id: brainstorm-YYYY-MM-DD-<goal-slug>
type: brainstorm
date: YYYY-MM-DD
---
# Brainstorm: <Goal>
## Problem Statement
## Approaches Considered
## Selected Approach
## Open Questions
## Next Step: /plan

5 つのセクションすべてを埋める必要があります。「Next Step」セクションには、選択したアプローチをコンテキストとして含む、具体的な /plan 呼び出しの提案を含めてください。

.agents/brainstorm/ ディレクトリが存在しない場合は作成してください。

---

アイデア創出モード(オープンエンドの generate-winnow)

上記の 4 フェーズフローへの追加であり、それを置き換えるものではありません。 アイデア創出モードは、「プロジェクトを改善する」といったスタイルの目標、つまり WHAT が不明で、1 つの既知の目標を明確化するのではなく、ポートフォリオを生成して選択する必要がある場合のためのものです。詳細: references/ideation-mode.md。

トリガー: フォローアップ後に単一の目標が現れない場合の exploring 明確化パス(フェーズ 1)、または明示的な --ideate フラグ、またはオープンエンドの目標文字列("improve the project"、"what should we build next"、"make X more robust")。

方法論は generate → winnow → expand → operationalize → refine です。ステップ 1〜3 は /brainstorm に属し、ステップ 4〜5 はオープンエンドパスの /discovery に引き渡されます(references/bead-operationalization.md を参照)。

ステップ 1 — 現実に基づく

アイデアが整合し、作業が重複しないように、プロジェクトの状態を読み取ります:

cat AGENTS.md                      # or CLAUDE.md — rules, constraints, non-goals
bd list --json                     # open work — don't duplicate
bd list --status closed --json     # closed work — don't re-propose cut ideas
bd ready --json                    # what is actionable now

ステップ 2 — 30 個を生成し、5 個に選別する(根拠付きでランク付け)

30 個の候補となる改善を生成します(基準 = ルーブリックの次元: robust、reliable、performant、intuitive、user-friendly、ergonomic、useful、compelling、かつ明らかに accretive で pragmatic であり続けること)。それぞれについて、どのように機能するか、ユーザーがどのように知覚するか、どのように実装するかを徹底的に考えます。次に、容赦なく最高の 5 個に選別し、完全な根拠とルーブリックスコアを付けて 最高から最低へランク付けして提示します。references/idea-rubric.md の選別ラウンドとスコアリングを適用し、生き残ったものを references/red-team-checklist.md でストレステストします。最初に思いついた 5 個で止めないでください — まず完全な 30 個を生成してください。

ステップ 3 — 次の 10 個で拡張する(→ 15)

次に優れた 10 個を生成し(それぞれ根拠付き)、15 個のランク付けされたポートフォリオを作ります — #6〜15 は多くの場合、トップ 5 を補完します。

ステップ 4〜5 — 運用化 + 洗練(/discovery に引き渡す)

ランク付けされた 15 個(how/perceive/implement のメモ + ルーブリックスコア + レッドチームの所見を含む)を先へ引き継ぎます。/discovery はそれらを自己文書化された bd ビーズ(依存関係 + 明示的なテストタスク)へと運用化し、プラン空間で 4〜5 回洗練します。references/bead-operationalization.md を参照してください。

出力

スタンドアロン(/brainstorm --ideate): ランク付けされたポートフォリオを .agents/brainstorm/YYYY-MM-DD-<slug>-ideation.md に書き込みます(テンプレートは references/ideation-mode.md にあります)。/discovery から呼び出された場合: 運用化ステップのために、ランク付けされたポートフォリオをインラインで返します。

トラッキングは bd であり、br/bv では決してありません — これは AgentOps です。

---

終了

フェーズ 4 の出力が書き込まれたら完了です。以降のフェーズはなく、ループもありません。

検証

出力ファイルを書き込んだ後、次の項目を確認します。

1. ファイルが想定されるパスに存在する
2. 5 つのセクション（Problem Statement、Approaches Considered、Selected Approach、Open Questions、Next Step: /plan）がすべて存在し、内容が空でない

ファイルパスをユーザーに報告してください。

---

例

例 1：具体的な目標

User: /brainstorm "add rate limiting to the API"

Phase 1: Goal is clear — add rate limiting to the API.
Phase 2: Problem is uncontrolled request volume causing timeouts.
         Benefits operators and end users. No rate limiting exists today.
Phase 3: Three approaches — token bucket middleware, API gateway,
         per-route decorators. User picks token bucket.
Phase 4: Writes .agents/brainstorm/2026-02-17-rate-limiting.md

例 2：曖昧な目標

User: /brainstorm "improve performance"

Phase 1: Goal is vague. Asks: "Which part? API response times,
         build speed, database queries, or something else?"
         User says: "API response times on the search endpoint."
Phase 2: Investigates search endpoint, finds N+1 queries.
Phase 3: Approaches — query optimization, caching layer, pagination.
Phase 4: Writes .agents/brainstorm/2026-02-17-search-performance.md

---

トラブルシューティング

問題	原因	解決策
Phase 1 のブレインストーミングが先に進まず、ループする	追加質問を行っても目標が曖昧なまま	具体的で検証可能な問題文を提示します（例：「パフォーマンスを改善する」ではなく「API の検索レイテンシーを 200ms 未満に短縮する」）。
出力ファイルに必須セクションが 1 つ以上ない	Phase 4 が中断されたか、スキルが早期に終了した	同じ目標で /brainstorm を再実行し、出力に 5 つのセクション（Problem Statement、Approaches Considered、Selected Approach、Open Questions、Next Step: /plan）がすべて存在することを確認します。
.agents/brainstorm/ ディレクトリが作成されない	スキルがディレクトリを作成できなかった（権限またはパスの問題）	mkdir -p .agents/brainstorm で手動作成し、再実行します。
「Next Step」セクションの /plan 呼び出しが汎用的、または不完全	選択したアプローチが具体性に欠け、具体的な計画コマンドを生成できなかった	出力ファイルを編集して選択したアプローチを明確にし、アプローチ名と主要な制約を含む /plan 呼び出しを作成します。
Phase 3 のブレインストーミングでアプローチが 1 つしか生成されない	問題の範囲が狭いか、目標に制約が多すぎる	目標の範囲を少し広げるか、代替アプローチを明示的に求めます（例：「キャッシュ方式とクエリ最適化方式を検討する」）。

---

関連項目

• skills/plan/SKILL.md — 選択したアプローチを実行可能な課題に分解します

参考ドキュメント

• references/brainstorm.feature — 実行可能な仕様：WHAT（何をするか）を明確にする 4 フェーズの確認、選択肢とトレードオフ、/plan 向けの Gherkin（正常系＋エッジケース）の記録（soc-qk4b）

• references/red-team-checklist.md — Phase 3b 向けの敵対的批評テンプレート

• references/ideation-mode.md — 自由形式の生成・絞り込み手法：モード選択表、30 件生成 → 5 件に絞り込み → 15 件に展開、出力テンプレート（ag-yw0）

• references/idea-rubric.md — 10 次元の評価基準（堅牢性／信頼性／パフォーマンス／直感的な使いやすさ／ユーザーフレンドリーさ／操作性／有用性／魅力／累積効果／実用性）＋絞り込みラウンド（ag-yw0）

• references/bead-operationalization.md — 優先順位付けしたポートフォリオを、自己文書化された bd ビーズ（依存関係＋テストタスク）に落とし込み、計画段階で 4～5 回洗練します（ag-yw0）