brainstorming

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

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

まず現在のプロジェクトのコンテキストを把握し、次にアイデアを練り上げるための質問を1つずつ尋ねます。構築するものを理解したら、デザインを提示してユーザーの承認を得ます。

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

アンチパターン：「これは簡単すぎてデザインは不要」

すべてのプロジェクトでこのプロセスを実施します。ToDo リスト、単一関数のユーティリティ、設定変更など、すべてが対象です。「簡単な」プロジェクトほど、検討されていない前提が大きな手戻りを生むものです。デザインは短くてもかまいません（本当に簡単なプロジェクトなら数文でも十分です）が、必ず提示して承認を得てください。

使用しない場合

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

チェックリスト

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

1. プロジェクトのコンテキストを調査する — ファイル、ドキュメント、最近のコミットを確認します
2. ビジュアルコンパニオンを提案する（話題にビジュアルに関する質問が含まれる場合）— 明確化の質問と同時ではなく、独立したメッセージで提案します。詳細は下記の「ビジュアルコンパニオン」セクションを参照してください。
3. 明確化の質問をする — 目的、制約、成功基準を把握するため、質問を1つずつ尋ねます
4. 2～3つのアプローチを提案する — トレードオフと推奨案を示します
5. デザインを提示する — 複雑さに応じてセクションを構成し、各セクションの後にユーザーの承認を得ます
6. デザインドキュメントを完成させる — 進行中のドラフト（「作業を進めながら保存する」を参照）を、Decision ログを含めて、選択した仕様フォルダー内の最終版に仕上げ、コミットします。新規プロジェクトでは docs/rubypowers/specs/ を使用します。docs/superpowers/specs/ がすでに存在する場合は、ドラフトと最終版をそこに保存します。
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/rubypowers/specs/ に保存します。docs/superpowers/specs/ がすでに存在する場合は、そのレガシーフォルダーをドラフト、昇格、最終保存、およびレビュアー向けの指示に使用します。ワークフロー全体を通して、選択した実際のフォルダーを使い続けてください。プロジェクトの仕様を両方の場所に分けて保存しないでください。
• 作成中のドラフトを <selected specs folder>/YYYY-MM-DD-<topic>-design.md に昇格します（DRAFT ヘッダーを削除します）
  • （仕様の保存場所についてユーザーが希望を示した場合は、その希望を優先します）
• 仕様には ## Decisions セクションを必ず含めてください。ブレインストーミングでユーザーが明示した決定をそれぞれ、原文どおり、またはほぼ原文どおりに記載し、1 行の根拠を添えます。後続の仕様レビューと計画への忠実性チェックでは、このセクションが基準になります。
• 利用可能な場合は、elements-of-style:writing-clearly-and-concisely スキルを使用します
• 設計ドキュメントを git にコミットします

仕様のセルフレビュー： 仕様ドキュメントを書いた後、改めて読み直します。

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

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

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

ユーザーレビューのゲート： 仕様レビューのループを通過したら、先に進む前に、作成した仕様をユーザーにレビューしてもらいます。

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

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

実装：

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

重要な原則

• 質問は 1 つずつ — 複数の質問でユーザーを困らせないでください
• 選択式を優先 — 可能な限り、自由回答より答えやすい選択式にします
• YAGNI を徹底する — すべての設計から不要な機能を取り除きます
• 代替案を検討する — 決定する前に、常に 2～3 個のアプローチを提案します
• 段階的に検証する — 設計を提示し、次に進む前に承認を得ます
• 柔軟に対応する — 何かが腑に落ちない場合は、立ち戻って確認します

合理化の一覧

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

危険信号 — 中止

• コミット済みの仕様がないままコードを書こうとしている
• 「進めてください」／「よさそうです」を実装の許可として扱っている
• 「何をしたか記録するため」に、コードを書いた後で仕様を書くつもりでいる
• 提示して承認された設計がないまま、アイデアから実装計画の作成に進もうとしている

これらはすべて、チェックリストに戻って現在の項目を完了する必要があることを意味します。

ビジュアルコンパニオン

ブレインストーミング中にモックアップ、図、視覚的な選択肢を表示するためのブラウザベースのコンパニオンです。モードではなくツールです。利用を承諾しても、すべての質問がブラウザ経由になるわけではありません。

コンパニオンの提案： モックアップ、レイアウト、図について視覚的な質問が予想される場合は、一度だけ利用の同意を求めます。

「作業中の内容によっては、ウェブブラウザーで表示したほうが説明しやすいものもありそうです。作業を進めながら、モックアップ、図、比較などのビジュアルを用意できます。この機能はまだ新しく、トークンを多く消費する場合があります。試してみますか？（ローカル URL を開く必要があります）」

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

承諾後の質問ごとの判断： ユーザーが「見る」ことで理解しやすくなる場合（モックアップ、レイアウトの比較、図）に限りブラウザーを使います。それ以外のテキストで扱える内容（要件、トレードオフ、範囲）にはターミナルを使います。UI に関する質問だからといって、自動的に視覚的な質問になるわけではありません。

承諾された場合は、先に詳細なガイド skills/brainstorming/visual-companion.md を読んでから進めてください。