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:

1. Explore Project Context

   Check files, documentation, and recent commits to understand the current state:

   # 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.

2. Ask Clarifying Questions

   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)
3. Propose 2-3 Approaches

   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...
   
4. Present Design

   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:

   Architecture

   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.
   

   Components

   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
   

   Data Flow

   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
   

   Error Handling

   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)
   

   Testing

   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
   
5. Write Design Document

   Save the validated design:

   # Create docs/plans directory if needed
   mkdir -p docs/plans
   
   # Save design with date prefix
   # Format: YYYY-MM-DD-<topic>-design.md
   cat > docs/plans/2026-03-09-metrics-tracking-design.md
   

   Commit the design document:

   git add docs/plans/2026-03-09-metrics-tracking-design.md
   git commit -m "docs: design for metrics tracking feature"
   
6. Transition to Implementation

   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

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

User Request

“Add a —verbose flag to show more output”

Brainstorming Session

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:

## 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: The next step after brainstorming - create detailed implementation plan
• 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-<topic>-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.