Skip to main content
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:
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
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

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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us