1---2name: brainstorming3description: Brainstorming refines vague or exploratory requests into a validated design document through structured clarifying dialogue and trade-off analysis before any implementation begins. Use when a user's request is under-specified, involves new feature or component design, describes new pipeline behavior, or lacks an existing spec — including when loaded by creating-a-pipeline Phase 0 for exploratory briefs.4---56# Brainstorming — Idea Refinement78<overview>9Brainstorming is the mandatory pre-flight phase for creative and design work. It enforces a strict "no-code-before-design" policy, guiding the orchestrator through context exploration, clarifying questions, and trade-off analysis to produce a validated design document (spec) that serves as the foundation for subsequent pipeline execution.10</overview>1112<glossary>13 <term name="Design Doc (Spec)">A persistent markdown file (e.g., `docs/specs/FEATURE-design.md`) capturing validated requirements.</term>14 <term name="Visual Companion">A browser-based tool for presenting mockups and diagrams during the design phase.</term>15 <term name="The Design Gate">The non-negotiable requirement for user approval of a design before any implementation begins.</term>16</glossary>1718## The Brainstorming Process1920<protocol>21### 1. CONTEXT & DECOMPOSITION22- Existing project structure, documentation, and recent commits are explored first.23- **Large-Scale Requests**: Requests describing multiple subsystems are decomposed into independent sub-projects before detail refinement.2425### 2. CLARIFYING DIALOGUE26- Clarifying questions focus on purpose, constraints, and success criteria.27- <invariant>Exactly one question is asked per message to avoid overwhelming the user.</invariant>28- Multiple-choice options (A/B/C) are preferred for faster decision-making. Example: "Which data store fits the scale requirement? A) SQLite (embedded, single-node), B) PostgreSQL (shared, multi-writer), C) Redis (ephemeral cache)."2930### 3. APPROACH & RECOMMENDATION31- Two to three architectural approaches are proposed with explicit trade-offs.32- A specific recommendation leads, with reasoning grounded in project context. Example: "Approach B is recommended because the existing service layer already exposes a PostgreSQL connection pool — adding SQLite would introduce a second persistence mechanism with no clear boundary."3334### 4. DESIGN PRESENTATION (THE GATE)35- The refined design is presented in logical sections: Architecture, Data Flow, Error Handling, Testing.36- <HARD-GATE>Code writing and project scaffolding are prohibited until the user has explicitly approved the presented design sections.</HARD-GATE>3738### 5. SPECIFICATION & REVIEW39- The design document is authored to `docs/specs/`.40- A **Spec Self-Review** is performed: placeholders, internal contradictions, and ambiguity are resolved before handoff.41- <HARD-GATE>The user is asked to review the final written spec file. Brainstorming is complete only upon user approval of the spec.</HARD-GATE>42</protocol>4344<invariants>45- NEVER combine the "Visual Companion" offer with other questions; it must be a standalone message.46- NEVER skip the design gate for "simple" projects; simplicity is often a mask for unexamined assumptions.47- ALWAYS design for isolation, breaking systems into smaller units with well-defined interfaces.48</invariants>4950## The Visual Companion Protocol5152<visual_companion_rules>53- **Offering**: When upcoming questions are visual in nature (layouts, diagrams), the companion is offered once in a standalone message.54- **Decision**: For each subsequent question, visual treatment (browser) or text treatment (terminal) is selected based on content type.55- **Browser**: Used for mockups, wireframes, and architecture diagrams.56- **Terminal**: Used for requirements, conceptual choices, and tradeoff lists.57</visual_companion_rules>5859## Red Flags — STOP60- "This is too simple to need a design." → **STOP**. Every project requires a validated design gate.61- "I'll ask 5 questions at once to save time." → **STOP**. One-question-per-message is mandatory for cognitive clarity.62- "I'll start scaffolding while we brainstorm." → **STOP**. Design must be approved before implementation begins.6364## Rationalization Table6566<rationalization_table>67| Excuse | Reality |68| :--- | :--- |69| "I'll fix the spec later." | A vague spec leads to divergent parallel workers. Fix all ambiguity during the design phase. |70| "Visuals take too many tokens." | Visuals prevent multi-turn misunderstandings that cost far more tokens in rework. |71| "The user already knows what they want." | Brainstorming surfaces implicit assumptions the user hasn't documented. |72</rationalization_table>7374## Reference Files75- `creating-a-pipeline/SKILL.md` — Implementation workflow.76- `sk-4d-method/SKILL.md` — Brief deconstruction.77- `sk-claude-code-conventions/SKILL.md` — Design patterns.78- `visual-companion.md` — Detailed browser usage guide.
gustavo-meilus