brainstorming

アイデアをデザインにまとめる

自然な対話を通じて、アイデアを完成度の高いデザインと仕様にまとめるのを支援します。

まず現在のプロジェクトの状況を把握し、次にアイデアを具体化するため、一度に1つずつ質問します。何を作るのかを理解したら、デザインを提示し、ユーザーの承認を得ます。

デザインを提示してユーザーの承認を得るまでは、実装スキルを呼び出したり、コードを書いたり、プロジェクトのひな形を作成したり、実装に関わる作業を行ったりしてはいけません。これは、簡単そうに見えるかどうかにかかわらず、すべてのプロジェクトに適用されます。

アンチパターン：「これは簡単だからデザインは不要」

すべてのプロジェクトでこのプロセスを実施してください。ToDoリスト、単一機能のユーティリティ、設定の変更など、すべてが対象です。「簡単な」プロジェクトほど、検討されていない前提が無駄な作業につながります。本当に簡単なプロジェクトなら、デザインは短く（数文程度で）構いませんが、必ず提示し、承認を得てください。

チェックリスト

次の各項目について必ずタスクを作成し、順番に完了してください。

1. プロジェクトの状況を調査する — ファイル、ドキュメント、最近のコミットを確認します
2. ビジュアルコンパニオンを必要なタイミングで提案する — 最初から提案してはいけません。質問内容を説明するより見せたほうが本当にわかりやすい場面が初めて訪れたときに、そのタイミングで提案します（独立したメッセージで提案）。承認されると、ブラウザーのタブが開きます。視覚的な質問が一度も生じない場合は、提案しないでください。以下の「ビジュアルコンパニオン」セクションを参照してください。
3. 明確化のための質問をする — 目的、制約、成功基準を理解するため、一度に1つずつ質問します
4. 2～3つのアプローチを提案する — トレードオフと推奨案を示します
5. デザインを提示する — 複雑さに応じてセクションを構成し、各セクションの後にユーザーの承認を得ます
6. デザインドキュメントを作成する — docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md に保存し、コミットします
7. 仕様をセルフレビューする — プレースホルダー、矛盾、曖昧さ、スコープを手短にその場で確認します（以下を参照）
8. ユーザーに作成した仕様をレビューしてもらう — 先に進む前に、仕様ファイルのレビューを依頼します
9. 実装に移る — writing-plans スキルを呼び出して、実装計画を作成します

プロセスの流れ

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"];
}

最終段階は writing-plans の呼び出しです。 frontend-design、mcp-builder、その他の実装スキルを呼び出してはいけません。ブレインストーミングの後に呼び出すスキルは、writing-plans だけです。

プロセス

アイデアを理解する：

• まず、現在のプロジェクトの状態（ファイル、ドキュメント、最近のコミット）を確認します
• 詳細な質問をする前に、範囲を評価します。依頼に複数の独立したサブシステム（例：「チャット、ファイルストレージ、請求、分析機能を備えたプラットフォームを構築する」）が記載されている場合は、すぐにその点を伝えます。まず分割が必要なプロジェクトについて、詳細を詰める質問に時間をかけないでください。
• プロジェクトが単一の仕様に収まらないほど大きい場合は、サブプロジェクトへの分解を支援します。独立した部分は何か、それらはどう関連しているか、どの順序で構築すべきかを整理します。その後、通常の設計フローに沿って最初のサブプロジェクトを検討します。各サブプロジェクトで、仕様 → 計画 → 実装のサイクルを個別に進めます。
• 適切な範囲のプロジェクトでは、アイデアを具体化するために、質問を一度に1つずつします
• 可能であれば選択式の質問を優先しますが、自由回答でもかまいません
• 1つのメッセージにつき質問は1つだけにします。あるトピックをさらに掘り下げる必要がある場合は、質問を複数に分けます
• 目的、制約、成功基準の理解に重点を置きます

アプローチを検討する：

• トレードオフの異なるアプローチを2～3案提示します
• 推奨案とその理由を説明しながら、会話形式で選択肢を提示します
• 推奨する選択肢を最初に示し、その理由を説明します

設計を提示する：

• 何を構築するのか理解できたと考えたら、設計を提示します
• 各セクションの詳しさは複雑さに応じて調整します。単純な内容なら数文、複雑な内容なら200～300語まで説明します
• 各セクションの後に、ここまでの内容で問題ないかを確認します
• アーキテクチャ、コンポーネント、データフロー、エラー処理、テストを扱います
• 不明点があれば、戻って確認する準備をしておきます

分離と明確さを重視して設計する：

• システムを、それぞれ明確な目的を持ち、定義されたインターフェースを通じて連携し、個別に理解・テストできる小さな単位に分割します
• 各単位について、何をするのか、どう使うのか、何に依存するのかを説明できるようにします
• 内部の実装を読まなくても、その単位の役割を理解できますか？内部実装を変更しても、利用側に影響はありませんか？そうでない場合は、境界を見直す必要があります。
• 適切に境界を定めた小さな単位は、作業もしやすくなります。一度にコンテキストに収められるコードのほうが推論しやすく、焦点の定まったファイルなら変更の信頼性も高まります。ファイルが大きくなっている場合は、役割を抱え込みすぎている兆候であることがよくあります。

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

• 変更を提案する前に、現在の構成を調べます。既存のパターンに従います。
• 既存コードの問題が作業に影響する場合（例：ファイルが大きくなりすぎている、境界が不明確、責務が複雑に絡み合っている）は、優れた開発者が作業中のコードを改善するように、対象を絞った改善を設計に含めます。
• 無関係なリファクタリングは提案しません。現在の目標に役立つことに集中します。

デザインの後

ドキュメント：

• 検証済みのデザイン（仕様）を docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md に記述します
  • （仕様の保存場所に関するユーザーの希望がある場合は、このデフォルトより優先します）
• 利用可能であれば、elements-of-style:writing-clearly-and-concisely スキルを使用します
• デザインドキュメントを git にコミットします

仕様のセルフレビュー： 仕様ドキュメントを書き終えたら、改めて見直します。

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

問題があれば、その場で修正します。再レビューは不要です。修正して先に進みます。

ユーザーレビューの確認： 仕様のレビューループを終えたら、先に進む前に、作成した仕様をユーザーに確認してもらいます。

"仕様を作成してコミットしました：<path>。実装計画の作成を始める前にご確認いただき、変更したい点があればお知らせください。"

ユーザーの返答を待ちます。変更を求められた場合は反映し、仕様のレビューループを再実行します。ユーザーの承認を得てから先に進みます。

実装：

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

主な原則

• 一度に質問は1つ - 複数の質問でユーザーを圧倒しないでください
• 選択式を優先 - 可能であれば、自由回答よりも回答しやすい形式にします
• YAGNIを徹底する - すべてのデザインから不要な機能を取り除きます
• 代替案を検討する - 決定する前に、常に2～3個のアプローチを提示します
• 段階的に検証する - デザインを提示し、次に進む前に承認を得ます
• 柔軟に対応する - 理解できない点があれば、戻って確認します

ビジュアルコンパニオン

ブレインストーミング中にモックアップ、図、ビジュアルな選択肢を表示するためのブラウザー型コンパニオンです。モードではなく、ツールとして利用できます。コンパニオンを利用するということは、視覚的な提示が役立つ質問で使えるという意味です。すべての質問をブラウザー経由で行うという意味ではありません。

コンパニオンの提案（必要なときに）： 最初から提案しないでください。説明するより見せたほうが本当にわかりやすい質問が出るまで待ちます。単なるUIの話題ではなく、実際のモックアップ、レイアウト、図に関する質問が対象です。そのような質問が初めて出たときに、独立したメッセージとして提案します。

"次の内容は、見せたほうがわかりやすいかもしれません。進めながら、ブラウザーのタブでモックアップ、図、比較を用意できます。まだ新しい機能で、トークンを多く消費することがあります。使ってみますか？こちらで開きます。"

この提案は必ず独立したメッセージにしてください。 提案だけを送り、確認質問、要約、その他の内容を含めないでください。ユーザーの返答を待ちます。承諾した場合は --open を付けてサーバーを起動し、ブラウザーが最初の画面を自動的に開くようにします。断られた場合はテキストのみで続け、ユーザーから再度持ち出されない限り、もう提案しないでください。

質問ごとの判断： ユーザーがコンパニオンの使用を承諾した後も、質問ごとにブラウザーとターミナルのどちらを使うか判断します。基準は、読むより見たほうがユーザーに理解しやすいかどうかです。

• ブラウザーを使う場合： 本質的に視覚的な内容 — モックアップ、ワイヤーフレーム、レイアウトの比較、アーキテクチャ図、並べて比較するビジュアルデザイン
• ターミナルを使う場合： テキストで伝える内容 — 要件に関する質問、概念的な選択肢、トレードオフの一覧、A/B/C/Dのテキスト選択肢、スコープの決定

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

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