> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/obra/superpowers/llms.txt > Use this file to discover all available pages before exploring further. # Brainstorming Ideas Into Designs > Turn ideas into fully-formed designs through collaborative dialogue before writing any code **HARD GATE**: Do NOT 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. ## Overview The Brainstorming skill helps turn vague ideas into concrete, approved designs through natural collaborative dialogue. It ensures you understand requirements, constraints, and success criteria before writing a single line of code. ## When to Use Use this skill **before any creative work**: * Creating new features * Building components * Adding functionality * Modifying behavior * Starting new projects 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 Process The brainstorming workflow follows six mandatory steps: Check files, documentation, and recent commits to understand the current state: ```bash theme={null} # Review recent changes git log --oneline -10 # Check project structure ls -la # Read existing docs cat README.md ``` Understanding existing patterns helps you design solutions that fit naturally. Ask questions **one at a time** to refine the idea: * **Prefer multiple choice** when possible (easier to answer) * Focus on: purpose, constraints, success criteria * Only one question per message * If a topic needs more exploration, break it into multiple questions **Good questions:** * "Should this be installed at user or system level?" * "For error handling, should we: A) retry automatically, B) return error to caller, or C) log and continue?" **Poor questions:** * "What should this do and how should it work and what errors might happen?" (too many at once) Present multiple approaches with trade-offs: * Lead with your **recommended option** and explain why * Include trade-offs for each approach * Present conversationally, not formally **Example:** ``` I see three approaches for the data storage: 1. **SQLite (recommended)**: Simple, no external dependencies, good enough for expected volume. Trade-off: harder to scale if requirements change dramatically. 2. PostgreSQL: More scalable, better for concurrent access. Trade-off: requires external service, more complex setup. 3. JSON files: Simplest possible. Trade-off: poor performance with many records, no concurrent access. I recommend SQLite because... ``` Once you understand what you're building, present the design: * **Scale sections to complexity**: A few sentences if straightforward, 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 sections:** High-level structure and key components: ``` ## Architecture The feature uses a three-layer architecture: - CLI layer: Handles user input and output formatting - Service layer: Core business logic - Storage layer: Data persistence Communication flows downward only (CLI → Service → Storage). No circular dependencies. ``` Individual pieces and their responsibilities: ``` ## Components **MetricsCollector** - Gathers usage data - Methods: track(event), flush() - Buffers events in memory, flushes every 100 items **MetricsExporter** - Exports to various formats - Formats: JSON, CSV, XML - Streaming for large datasets ``` How data moves through the system: ``` ## Data Flow 1. User triggers command: `metrics export --format json` 2. CLI validates format, creates Exporter 3. Exporter queries Storage for data 4. Exporter streams formatted output to stdout 5. User can redirect to file ``` What can go wrong and how you'll handle it: ``` ## Error Handling - Invalid format: Show error + valid formats, exit 1 - Storage unavailable: Show error, exit 2 - Partial data: Complete export, log warning - No data: Show "0 records", exit 0 (success) ``` How you'll verify it works: ``` ## Testing Unit tests: - Each component in isolation - Mock dependencies (Storage for Service tests) Integration tests: - Full export flow - Each supported format - Error conditions ``` Save the validated design: ```bash theme={null} # Create docs/plans directory if needed mkdir -p docs/plans # Save design with date prefix # Format: YYYY-MM-DD--design.md cat > docs/plans/2026-03-09-metrics-tracking-design.md ``` Commit the design document: ```bash theme={null} git add docs/plans/2026-03-09-metrics-tracking-design.md git commit -m "docs: design for metrics tracking feature" ``` The **only** next step is invoking the writing-plans skill: ``` I'll now invoke the writing-plans skill to create a detailed implementation plan. ``` Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans. ## Key Principles ### One Question at a Time Don't overwhelm with multiple questions. Ask one, wait for answer, ask next. **Good:** ``` Should the hook be installed at user or system level? ``` **Bad:** ``` Should the hook be installed at user or system level? What should the file permissions be? Should we support Windows? ``` ### Multiple Choice Preferred Easier to answer than open-ended when possible. **Good:** ``` For conflict handling, should we: A) Abort and show error B) Auto-merge if possible C) Ask user to choose ``` **Bad:** ``` How should we handle conflicts? ``` ### YAGNI Ruthlessly You Aren't Gonna Need It. Remove unnecessary features from all designs. **Example:** ``` Original idea: "Metrics tracking with export to 10 formats, real-time dashboard, and cloud sync" After YAGNI: "Metrics tracking with export to JSON and CSV" Rationale: Start with what's needed now. Add formats later if actually needed. Dashboard and cloud sync are premature. ``` ### Explore Alternatives Always propose 2-3 approaches before settling on one. ### Incremental Validation Present design section by section, get approval before moving on. ### Be Flexible Go back and clarify when something doesn't make sense. Design is iterative. ## Anti-Pattern: "This Is Too Simple" Never skip the design process because a project seems simple. Simple projects are where unexamined assumptions cause the most wasted work: * **Todo list app**: Seems simple, but sync strategy affects entire architecture * **Single-function utility**: Seems simple, but error handling and edge cases matter * **Config change**: Seems simple, but migration path and backwards compatibility matter The design can be short (a few sentences for truly simple projects), but you **MUST** present it and get approval. ## Process Flow ```mermaid theme={null} graph TD A[Explore project context] --> B[Ask clarifying questions] B --> C[Propose 2-3 approaches] C --> D[Present design sections] D --> E{User approves design?} E -->|No, revise| D E -->|Yes| F[Write design doc] F --> G[Invoke writing-plans skill] ``` ## Red Flags If you catch yourself thinking: * "This is too simple to need a design" * "I know what they want, let's just start coding" * "We can figure out the details as we go" * "Design will just slow us down" **STOP.** These are rationalizations. Follow the process. ## Example: Quick Feature "Add a --verbose flag to show more output" **Explore Context:** * Check existing flags: `--quiet`, `--json` * Review current output format **Clarifying Questions:** ``` Q: What additional information should --verbose show? A: Show each file being processed Q: Should --verbose and --json work together? A: No, they're mutually exclusive ``` **Design:** ```markdown theme={null} ## Design: Verbose Flag Add --verbose/-v flag to CLI. **Behavior:** - Without flag: Show only summary (current behavior) - With --verbose: Show each file + summary - With --verbose --json: Error, mutually exclusive **Implementation:** - Add flag to CLI parser - Pass verbosity to processor - Processor logs each file if verbose **Testing:** - Test verbose output format - Test without verbose (unchanged) - Test verbose + json (error) ``` Even a simple flag benefits from thinking through interactions. ## Related Skills * **[Writing Plans](/skills/writing-plans)**: The next step after brainstorming - create detailed implementation plan * **[Systematic Debugging](/skills/systematic-debugging)**: Use similar investigative approach when debugging ## Checklist Before moving to implementation: * [ ] Explored project context (files, docs, commits) * [ ] Asked clarifying questions (one at a time) * [ ] Understood purpose, constraints, success criteria * [ ] Proposed 2-3 approaches with trade-offs * [ ] Presented design covering architecture, components, data flow, errors, testing * [ ] Got user approval on design * [ ] Wrote design doc to `docs/plans/YYYY-MM-DD--design.md` * [ ] Committed design doc * [ ] Ready to invoke writing-plans skill The time spent on brainstorming is saved many times over by avoiding wrong implementations, missed requirements, and architectural dead ends.