Brainstorming アイデアをデザインへ

自然な対話を通じた協働により、アイデアを完成されたデザインや仕様へと形にしていきましょう。

まずは現在のプロジェクトの背景を理解することから始め、次に質問を一つずつ投げかけてアイデアを具体化していきます。何を作るのかが明確になったら、デザインを提示し、ユーザーの承認を得ます。

アンチパターン：「これは単純すぎてデザインなど必要ない」

どのプロジェクトもこのプロセスを経ます。ToDoリスト、単一機能のユーティリティ、設定の変更――すべてがそうです。「単純な」プロジェクトこそ、検証されていない前提が最も多くの無駄な作業を引き起こす場なのです。設計内容は短くても構いません（本当に単純なプロジェクトなら数行程度でも）が、必ず提示して承認を得なければなりません。

チェックリスト

以下の各項目についてタスクを作成し、順番に完了させなければなりません：

プロジェクトの背景を調査する— ファイル、ドキュメント、最近のコミットを確認する
視覚的な補助資料は「ジャストインタイム」で提示する— 事前に提示してはならない。説明よりも図示した方が明らかに分かりやすいと真に判断できる最初のタイミングで提示する（独立したメッセージとして）。承認されれば、そのブラウザタブが自動的に開かれる。視覚的な疑問が一切生じない場合は、決して提示してはならない。以下の「視覚的な補助資料」のセクションを参照のこと。
明確化のための質問を行う— 1つずつ、目的・制約・成功基準を理解する
2～3つのアプローチを提案する— トレードオフと推奨案を併せて提示する
設計を提示する— 複雑さに応じてセクション分けし、各セクションごとにユーザーの承認を得る
設計文書を作成する—docs/superpowers/specs/YYYY-MM-DD--design.mdに保存し、コミットする
仕様書の自己レビュー— プレースホルダー、矛盾、曖昧さ、範囲について、インラインで手早く確認する（下記参照）
ユーザーによる仕様書のレビュー— 作業を進める前に、ユーザーに仕様ファイルのレビューを依頼する
実装への移行— writing-plansスキルを活用して実装計画を作成する

プロセスフロー

digraphbrainstorming {
    "プロジェクトの背景を調査する" [shape=box];
    "明確化のための質問を行う" [shape=box];
    "2～3つのアプローチを提案する" [shape=box];
    "設計セクションを提示する" [shape=box];
    "ユーザーが設計を承認するか？" [shape=diamond];
    "設計文書を作成する" [shape=box];
    "仕様書の自己レビュー\n（インラインで修正）" [shape=box];
    "ユーザーが仕様書をレビューするか？" [shape=diamond];
    "執筆計画のスキルを発動" [shape=doublecircle];

    "プロジェクトの背景を調査" -> "確認のための質問をする";
    "確認のための質問をする" -> "2～3つのアプローチを提案";
    "2～3つのアプローチを提案" -> "設計セクションを提示";
    "設計セクションを提示" -> "ユーザーが設計を承認するか？";
    "ユーザーが設計を承認するか？" -> "設計セクションを提示" [label="いいえ、修正"];
    "ユーザーが設計を承認するか？" -> 「設計文書を作成する」 [label="はい"];
    「設計文書を作成する」 -> 「仕様書の自己レビュー\n（その場で修正）」;
    「仕様書の自己レビュー\n（その場で修正）」 -> 「ユーザーが仕様書をレビューするか？」;
    "ユーザーが仕様書をレビューしましたか？" -> "設計ドキュメントを作成" [label="変更要求あり"];
    "ユーザーが仕様書をレビューしましたか？" -> "writing-plansスキルを起動" [label="承認済み"];
}

終端状態は「writing-plans」の呼び出しです。「frontend-design」、「mcp-builder」、またはその他の実装スキルは絶対に呼び出さないでください。「brainstorming 」の後に呼び出すスキルは、「writing-plans」のみです。

プロセス

コンセプトの理解：

まず、現在のプロジェクトの状態（ファイル、ドキュメント、最近のコミット）を確認する
詳細な質問をする前に、範囲を評価する：リクエストに複数の独立したサブシステムが含まれている場合（例：「チャット、ファイルストレージ、課金、分析機能を備えたプラットフォームを構築する」など）、直ちにその旨を指摘する。まず分解が必要なプロジェクトの詳細を、質問を通じて絞り込むことに時間を費やしてはならない。
プロジェクトが単一の仕様書で扱える範囲を超えている場合は、ユーザーがサブプロジェクトに分解できるよう支援する：独立した構成要素は何か、それらはどのように関連しているか、どの順序で構築すべきか？その後、通常の設計フローに従って最初のサブプロジェクトについてブレインストーミングを行う。各サブプロジェクトには、独自の「仕様書 → 計画 → 実装」サイクルが設けられる。
適切な範囲のプロジェクトについては、アイデアを具体化するために質問を一つずつ投げかけましょう
可能であれば選択式の問題を優先しますが、自由回答形式でも構いません
1つのメッセージにつき1つの質問のみ。トピックについてさらに掘り下げる必要がある場合は、複数の質問に分割してください
理解に焦点を当てる：目的、制約、成功基準

アプローチの検討：

トレードオフを考慮した上で、2～3種類の異なるアプローチを提案する
自分の推奨案とその根拠を交えながら、会話形式で選択肢を提示してください
推奨する選択肢を最初に提示し、その理由を説明してください

設計の提示：

構築する内容を理解できたと判断したら、設計案を提示する
各セクションは、その複雑さに応じて分量を調整してください。単純な場合は数文、ニュアンスが複雑な場合は200～300語程度を目安にしてください
各セクションの説明が終わるたびに、ここまでの内容に問題がないか確認する
カバーすべき内容：アーキテクチャ、コンポーネント、データフロー、エラー処理、テスト
理解できない点があれば、戻って説明を明確にする準備をしておくこと

分離性と明瞭性を重視した設計を行う：

システムを、それぞれが明確な目的を持ち、明確に定義されたインターフェースを通じて通信し、独立して理解・テスト可能な小さな単位に分割する
各ユニットについて、「何をするのか」「どのように使うのか」「何に依存しているのか」という質問に答えられるようにすべきです
そのユニットの内部構造を読まなくても、その動作を理解できるでしょうか？利用者への影響を与えずに内部を変更できますか？そうでない場合は、境界の見直しが必要です。
小さく、境界が明確なユニットは、開発者にとっても扱いやすいものです。一度に文脈を把握できるコードの方が論理的に考えやすく、ファイルの焦点が絞られていると編集の信頼性も高まります。ファイルが大きくなりすぎている場合は、そのファイルが担う役割が多すぎるというサインであることが多いのです。

既存のコードベースでの作業：

変更を提案する前に、現在の構造を精査してください。既存のパターンに従ってください。
既存のコードに作業に影響を与える問題（例：ファイルが肥大化しすぎている、境界が不明確、責任範囲が絡み合っているなど）がある場合は、優れた開発者が担当しているコードを改善するように、設計の一部として的を絞った改善を含めてください。
無関係なリファクタリングを提案しないでください。現在の目標達成に役立つことに集中してください。

設計後

ドキュメント化:

検証済みの設計（仕様書）をdocs/superpowers/specs/YYYY-MM-DD--design.mdに記述してください
- （仕様の保存場所に関するユーザー設定が、このデフォルト設定に優先されます）
可能であれば、elements-of-style:writing-clearly-and-conciseのスキルを活用してください
設計文書をGitにコミットしてください

仕様書の自己レビュー： 仕様書を作成した後、新鮮な目で内容を確認してください：

プレースホルダーの確認：「TBD」、「TODO」、未完成のセクション、または曖昧な要件はありませんか？それらを修正してください。
内部の一貫性：互いに矛盾するセクションはありませんか？アーキテクチャは機能の説明と一致していますか？
スコープの確認：単一の実装計画として十分に焦点が絞られているか、それとも分解が必要か？
曖昧さの確認：要件の解釈が2通りあり得るものはありますか？ある場合は、どちらか一方を選び、明確に記述してください。

問題はすべてその場で修正してください。再レビューの必要はありません。修正して次に進みましょう。

ユーザーレビューのゲート： 仕様書のレビューループを通過した後、作業を進める前にユーザーに作成された仕様書のレビューを依頼してください：

「仕様書を作成し、にコミットしました。実装計画の作成を始める前に、内容を確認し、変更希望があればお知らせください。」

ユーザーの返信を待ちます。変更の要望があれば、それに対応し、仕様書レビューのループを再度実行してください。ユーザーの承認が得られてから初めて、次の段階に進んでください。

実装：

writing-plans スキルを呼び出して、詳細な実装計画を作成します
他のスキルを絶対に呼び出さないでください。「writing-plans」が次のステップです。

重要な原則

一度に1つの質問のみ― 複数の質問で相手を圧倒しない
可能であれば、自由記述式よりも選択式を優先する— 回答しやすいため
YAGNIを徹底する— すべての設計から不要な機能を排除する
代替案を検討する- 決定する前に、常に2～3つのアプローチを提案する
段階的な検証— 設計案を提示し、承認を得てから次の段階に進む
柔軟に対応する- 意味が通じない場合は、戻って明確化する

ビジュアルコンパニオン

brainstorming の進行中に、モックアップ、図、視覚的な選択肢を表示するためのブラウザベースの補助ツール。これは「モード」ではなく「ツール」として利用可能です。この補助ツールの使用を許可するということは、視覚的な表現が有効な質問に対してのみ利用可能であることを意味します。すべての質問がブラウザ経由で行われることを意味するものではありません。

コンパニオンの提案（ジャスト・イン・タイム）：最初から提案してはいけません。単にUIの話題ではなく、説明するよりも実際に見せた方が明らかに理解しやすくなる質問（実際のモックアップ／レイアウト／図表に関する質問）が出るまで待ちましょう。そのような状況が初めて生じた時点で、次のようなメッセージとして提案します：

「次の部分は、実際に見せたほうが分かりやすいかもしれません。進めながら、ブラウザのタブでモックアップや図解、比較表を作成できます。まだ新しい機能で、トークンを多く消費する可能性があります。試してみますか？開いておきますよ。」

この提案は、必ず独立したメッセージとして送ってください。提案のみ——説明のための質問や要約、その他の内容は一切含めないでください。ユーザーの反応を待ちます。承諾された場合は、--open オプションを指定してサーバーを起動し、ユーザーのブラウザが自動的に最初の画面で開くようにします。断られた場合は、テキストのみのやり取りを続け、ユーザーからその話題が出ない限り、再度提案しないでください。

質問ごとの判断：ユーザーが承諾した後も、各質問ごとにブラウザを使うかターミナルを使うかを判断してください。判断基準は、「ユーザーがこれを読むよりも、目で見せたほうが理解しやすいか」です。

視覚的なコンテンツ（モックアップ、ワイヤーフレーム、レイアウトの比較、アーキテクチャ図、並列表示されたビジュアルデザインなど）にはブラウザを使用する
テキストベースのコンテンツにはターミナルを使用する— 要件に関する質問、概念的な選択、トレードオフのリスト、A/B/C/Dのテキスト選択肢、スコープの決定

UIに関する質問であっても、必ずしも視覚的な質問とは限りません。「この文脈において『パーソナリティ』とは何を意味するか？」は概念的な質問であるため、ターミナルを使用します。「どのウィザードのレイアウトがより効果的か？」は視覚的な質問であるため、ブラウザを使用します。

コンパニオンガイドの使用に同意した場合は、先に進む前に詳細ガイドをお読みください： skills/brainstorming/visual-companion.md

GitHubで見る

---
name: brainstorming
description: Guides collaborative dialogue to turn ideas into fully formed designs and specs before any implementation begins.
---

# Brainstorming Ideas Into Designs

Help turn ideas into fully formed designs and specs through natural collaborative dialogue.

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
</HARD-GATE>

## Anti-Pattern: "This Is Too Simple To Need A Design"

Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.

## Checklist

You MUST create a task for each of these items and complete them in order:

1. **Explore project context** — check files, docs, recent commits
2. **Offer the visual companion just-in-time** — NOT upfront. The first time a question would genuinely be clearer shown than described, offer it then (its own message); on approval its browser tab opens for you. If no visual question ever arises, never offer it. See the Visual Companion section below.
3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
4. **Propose 2-3 approaches** — with trade-offs and your recommendation
5. **Present design** — in sections scaled to their complexity, get user approval after each section
6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
8. **User reviews written spec** — ask user to review the spec file before proceeding
9. **Transition to implementation** — invoke writing-plans skill to create implementation plan

## Process Flow

```dot
digraph brainstorming {
    "Explore project context" [shape=box];
    "Ask clarifying questions" [shape=box];
    "Propose 2-3 approaches" [shape=box];
    "Present design sections" [shape=box];
    "User approves design?" [shape=diamond];
    "Write design doc" [shape=box];
    "Spec self-review\n(fix inline)" [shape=box];
    "User reviews spec?" [shape=diamond];
    "Invoke writing-plans skill" [shape=doublecircle];

    "Explore project context" -> "Ask clarifying questions";
    "Ask clarifying questions" -> "Propose 2-3 approaches";
    "Propose 2-3 approaches" -> "Present design sections";
    "Present design sections" -> "User approves design?";
    "User approves design?" -> "Present design sections" [label="no, revise"];
    "User approves design?" -> "Write design doc" [label="yes"];
    "Write design doc" -> "Spec self-review\n(fix inline)";
    "Spec self-review\n(fix inline)" -> "User reviews spec?";
    "User reviews spec?" -> "Write design doc" [label="changes requested"];
    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
}
```

**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.

## The Process

**Understanding the idea:**

- Check out the current project state first (files, docs, recent commits)
- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
- For appropriately-scoped projects, ask questions one at a time to refine the idea
- Prefer multiple choice questions when possible, but open-ended is fine too
- Only one question per message - if a topic needs more exploration, break it into multiple questions
- Focus on understanding: purpose, constraints, success criteria

**Exploring approaches:**

- Propose 2-3 different approaches with trade-offs
- Present options conversationally with your recommendation and reasoning
- Lead with your recommended option and explain why

**Presenting the design:**

- Once you believe you understand what you're building, present the design
- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
- Ask after each section whether it looks right so far
- Cover: architecture, components, data flow, error handling, testing
- Be ready to go back and clarify if something doesn't make sense

**Design for isolation and clarity:**

- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.

**Working in existing codebases:**

- Explore the current structure before proposing changes. Follow existing patterns.
- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
- Don't propose unrelated refactoring. Stay focused on what serves the current goal.

## After the Design

**Documentation:**

- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
  - (User preferences for spec location override this default)
- Use elements-of-style:writing-clearly-and-concisely skill if available
- Commit the design document to git

**Spec Self-Review:**
After writing the spec document, look at it with fresh eyes:

1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.

Fix any issues inline. No need to re-review — just fix and move on.

**User Review Gate:**
After the spec review loop passes, ask the user to review the written spec before proceeding:

> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."

Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.

**Implementation:**

- Invoke the writing-plans skill to create a detailed implementation plan
- Do NOT invoke any other skill. writing-plans is the next step.

## Key Principles

- **One question at a time** - Don't overwhelm with multiple questions
- **Multiple choice preferred** - Easier to answer than open-ended when possible
- **YAGNI ruthlessly** - Remove unnecessary features from all designs
- **Explore alternatives** - Always propose 2-3 approaches before settling
- **Incremental validation** - Present design, get approval before moving on
- **Be flexible** - Go back and clarify when something doesn't make sense

## Visual Companion

A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.

**Offering the companion (just-in-time):** Do NOT offer it upfront. Wait until a question would genuinely be clearer shown than told — a real mockup / layout / diagram question, not merely a UI *topic*. The first time that happens, offer it then, as its own message:
> "This next part might be easier if I show you — I can put together mockups, diagrams, and comparisons in a browser tab as we go. It's still new and can be token-intensive. Want me to? I'll open it for you."

**This offer MUST be its own message.** Only the offer — no clarifying question, summary, or other content. Wait for the user's response. If they accept, start the server with `--open` so their browser opens to the first screen automatically. If they decline, continue text-only and don't offer again unless they raise it.

**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**

- **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
- **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions

A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser.

If they agree to the companion, read the detailed guide before proceeding:
`skills/brainstorming/visual-companion.md`