brainstorming

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

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

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

デザインが提示され承認されていること、仕様書が作成されコミットされていること、ユーザーが作成された仕様書を確認していること、そして writing-plans スキルが呼び出されていることのすべてを満たすまでは、コードの作成、プロジェクトの雛形の作成、実装スキルの呼び出し、その他の実装作業を絶対に行わないでください。デザインに対するチャットでの承認（「よさそうです。進めてください」）で完了するのは、チェックリストの次の項目だけです。実装の許可ではありません。これは、簡単に見えるかどうかにかかわらず、すべてのプロジェクトに適用されます。

アンチパターン：「デザインが必要なほど複雑ではない」

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

使用しない場合

• デバッグ／リグレッションの修正 — superpowers-ruby:systematic-debugging を使用してください。修正によって意図された動作が変わると判明した場合は、ここに戻ってください。
• すでに承認された計画の実行 — superpowers-ruby:executing-plans または subagent-driven-development を使用してください。
• 純粋な調査や質問 — 実装に進まないのであれば、デザインするものはありません。

チェックリスト

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

1. プロジェクトの状況を把握する — ファイル、ドキュメント、最近のコミットを確認します
2. ビジュアルコンパニオンを提案する（視覚的な質問が関係する場合）— これは確認質問とは別のメッセージで送ります。詳しくは下記の「ビジュアルコンパニオン」セクションを参照してください。
3. 確認質問をする — 目的、制約、成功基準を理解するため、質問を一つずつ行います
4. 2～3つのアプローチを提案する — トレードオフと推奨案を示します
5. デザインを提示する — 複雑さに応じたセクションに分け、各セクションの後にユーザーの承認を得ます
6. デザイン文書を完成させる — 作業中のドラフト（「作業を進めながら記録する」を参照）を、Decision log を含む最終版として docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md にまとめ、コミットします
7. 仕様書を自己レビューする — プレースホルダー、矛盾、曖昧さ、対象範囲を簡単にその場で確認します（下記参照）
8. ユーザーに仕様書を確認してもらう — 続行する前に、仕様書ファイルを確認するようユーザーに依頼します
9. 実装に移行する — writing-plans スキルを呼び出して実装計画を作成します

プロセスの流れ

digraph brainstorming {
    "Explore project context" [shape=box];
    "Visual questions ahead?" [shape=diamond];
    "Offer Visual Companion\n(own message, no other content)" [shape=box];
    "Ask clarifying questions" [shape=box];
    "Create DRAFT spec\n(append decisions as they land)" [shape=box];
    "Propose 2-3 approaches" [shape=box];
    "Present design sections" [shape=box];
    "User approves design?" [shape=diamond];
    "Finalize design doc\n(promote DRAFT, add Decisions)" [shape=box];
    "Spec self-review\n(fix inline)" [shape=box];
    "User reviews spec?" [shape=diamond];
    "Invoke writing-plans skill" [shape=doublecircle];

    "Explore project context" -> "Visual questions ahead?";
    "Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
    "Offer Visual Companion\n(own message, no other content)" -> "Ask clarifying questions";
    "Ask clarifying questions" -> "Create DRAFT spec\n(append decisions as they land)";
    "Create DRAFT spec\n(append decisions as they land)" -> "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?" -> "Ask clarifying questions" [label="no, misunderstood the goal"];
    "User approves design?" -> "Finalize design doc\n(promote DRAFT, add Decisions)" [label="yes"];
    "Finalize design doc\n(promote DRAFT, add Decisions)" -> "Spec self-review\n(fix inline)";
    "Spec self-review\n(fix inline)" -> "User reviews spec?";
    "User reviews spec?" -> "Finalize design doc\n(promote DRAFT, add Decisions)" [label="changes requested"];
    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
}

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

プロセス

アイデアを理解する：

• まず、現在のプロジェクトの状態（ファイル、ドキュメント、最近のコミット）を確認します
• 詳細を質問する前に、範囲を見極めます。依頼に複数の独立したサブシステム（例：「チャット、ファイルストレージ、請求、分析を備えたプラットフォームを構築する」）が含まれている場合は、すぐにそのことを伝えます。まず分割が必要なプロジェクトについて、詳細を詰める質問に時間を費やさないでください。
• プロジェクトが単一の仕様に収まらないほど大きい場合は、ユーザーがサブプロジェクトに分割できるよう支援します。独立した要素は何か、それらはどう関係するか、どの順序で構築すべきかを検討します。その後、通常の設計の流れに沿って、最初のサブプロジェクトについてブレインストーミングします。各サブプロジェクトで、仕様 → 計画 → 実装のサイクルを進めます。
• 適切な範囲のプロジェクトでは、アイデアを具体化するために一度に1つずつ質問します
• 可能な場合は選択式の質問を優先しますが、自由回答式でもかまいません。AskUserQuestion ツールを利用できる場合は、選択肢の提示に使用します。
• 基本は1回のメッセージにつき1つの質問です。さらに掘り下げる必要がある場合は、複数の質問に分けます
• 例外：質問同士が本当に独立していて（ある質問への回答が別の質問に影響しない場合）、ユーザーが時間に追われているときなどは、AskUserQuestion の1回の呼び出しで最大4つの選択式質問をまとめて提示できます。回答に依存する質問をまとめて提示してはいけません。
• 目的、制約、成功基準の理解に重点を置きます

進行に合わせて記録する：

• 実質的な決定が出始めたらすぐに、ドラフトとして仕様ファイルを作成します（先頭に Status: DRAFT ヘッダーを置きます）。決定が確定するたびに追記します
• チャット履歴は記録として使えません。セッションがクラッシュ、圧縮、中断されても、ブレインストーミングの内容が失われないようにします。ドラフトファイルを、次のセッションが再開するための記録にします。

アプローチを検討する：

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

設計を提示する：

• 何を構築するのか理解できたら、設計を提示します
• 各セクションの詳しさは複雑さに合わせます。単純な内容なら数文、複雑な内容なら最大200～300語程度にします
• 各セクションの後に、ここまでの内容で問題ないか確認します
• アーキテクチャ、コンポーネント、データフロー、エラー処理、テストを扱います
• 不明な点があれば、立ち戻って確認できるようにします

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

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

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

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

デザイン後

ドキュメント：

• 実行中のドラフトを、docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md に最終仕様として昇格させます（DRAFT ヘッダーを削除します）
  • （仕様書の保存場所に関するユーザーの希望がある場合は、こちらが優先されます）
• 仕様書には ## Decisions セクションを必ず含めます。ブレインストーミングでユーザーが明示したすべての決定を、原文どおり、またはほぼ原文どおりに記載し、それぞれに1行の根拠を添えます。後続の仕様書レビューと計画との整合性チェックでは、このセクションを基準にします。
• 利用可能な場合は elements-of-style:writing-clearly-and-concisely スキルを使用します
• デザインドキュメントを git にコミットします

仕様書のセルフレビュー： 仕様書を書いたら、いったん新鮮な目で確認します。

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

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

複雑な仕様書や重要度の高い仕様書では、さらに spec-document-reviewer-prompt.md（このスキルと同じディレクトリにあります）のテンプレートを使い、新しいコンテキストのレビュアーサブエージェントを呼び出します。小規模な仕様書では省略し、インラインでの確認だけで十分です。

ユーザーレビューのゲート： 仕様書のレビューサイクルを終えたら、次に進む前に、作成した仕様書をユーザーに確認してもらいます。

「仕様書を <path> に作成し、コミットしました。内容を確認し、実装計画の作成に進む前に変更したい点があればお知らせください。」

ユーザーの返答を待ちます。変更の要望があれば反映し、仕様書のレビューサイクルを再度実施します。ユーザーの承認を得てから先に進みます。

実装：

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

主な原則

• 一度に質問は1つ — 複数の質問をまとめてユーザーに負担をかけないでください
• 選択式を優先 — 可能な場合は、自由回答よりも答えやすい形式にします
• YAGNI を徹底する — すべてのデザインから不要な機能を取り除きます
• 代替案を検討する — 決定する前に、必ず2〜3案を提示します
• 段階的に確認する — デザインを提示し、次に進む前に承認を得ます
• 柔軟に対応する — 何か納得できない点があれば、立ち戻って確認します

合理化の言い訳一覧

言い訳	現実
「ユーザーは求めていることを正確に伝えている」	ユーザーが示したのは解決策であり、その中に隠れている未決定事項ではありません。3文のデザインと一言の承認を求めれば、数秒でそれを明らかにできます。
「ユーザーがデザインプロセスを省略してよいと言った」	省略ではなく短縮します。可能な限り短いデザインを提示し、承認を1回求めます。速さは、ゲートを省くことではなく、簡潔さから生まれます。
「チャットで承認されたので、コードを書いてよい」	チャットでの承認で完了するのは、チェックリストの1項目だけです。仕様書の作成 → コミット → 書面での仕様書レビュー → writing-plans は、すべて必要です。
「ドキュメントは小規模だから省略する」	コミット済みの仕様書をもとに、計画や今後のセッションを進めます。チャット履歴は消えてしまいます。ユーザーが承認したのはチャットの短文であり、レビュー済みの仕様書ではありません。
「時間を節約するため、デザインとコードをまとめて提示する」	ゲートの目的が損なわれます。作業に着手する前に誤った前提を見つける必要があります。そうでなければ、すでに時間を無駄にしています。

危険信号 — 中断してください

• コミット済みの仕様書がないまま、コードを書こうとしている
• 「進めてください」や「よさそうです」を、実装の許可として扱っている
• 「何をしたか記録するため」に、コードを書いた後で仕様書を作成しようとしている
• 提示して承認されたデザインを経ず、アイデアから直接 writing-plans に進もうとしている

これらに当てはまる場合は、チェックリストに戻り、現在の項目を完了してください。

ビジュアルコンパニオン

ブレインストーミング中にモックアップ、図、ビジュアル案を表示するためのブラウザベースのコンパニオンです。モードではなくツールです。これを受け入れても、すべての質問がブラウザ経由になるわけではありません。

コンパニオンの提案： モックアップ、レイアウト、図など、ビジュアルを使った質問が予想される場合は、同意を得るために一度だけ提案してください。

「今取り組んでいる内容の中には、ウェブブラウザでお見せすると、より分かりやすく説明できるものがあるかもしれません。作業を進めながら、モックアップ、図、比較資料などを作成できます。この機能はまだ新しく、トークンを多く消費する場合があります。試してみますか？（ローカル URL を開く必要があります）」

この提案は必ず単独のメッセージにしてください。ほかの内容は含めず、返答を待ってください。断られた場合は、テキストのみで進めてください。

受け入れ後の質問ごとの判断： ユーザーが見て理解するほうがよい場合（モックアップ、レイアウトの比較、図など）に限りブラウザを使ってください。テキストで扱う内容（要件、トレードオフ、範囲など）にはターミナルを使ってください。UI に関する質問だからといって、自動的にビジュアルを使う質問になるわけではありません。

受け入れられた場合は、先に詳細ガイドを読んでください：skills/brainstorming/visual-companion.md