Brainstorming Skill

Purpose: Explore user intent, requirements, and design before any implementation begins.

The Iron Rule

HARD-GATE: Do NOT invoke any implementation skill, write code, scaffold, or take implementation action until user approves the design.

Workflow

Step 1: Explore Project Context

Read existing files, docs, recent commits, and any relevant project state to understand the landscape.

Also load these project-level phase files if they exist:

• STATE.md — cross-session decisions, blockers, current state
• ROADMAP.md — phases, milestones, progress
• REQUIREMENTS.md — scoped requirements with phase traceability
• {phase}-CONTEXT.md — implementation decisions for the current phase

These files live in the project root alongside PROJECT.md. They capture context that should persist across sessions.

Step 2: Visual Companion (Optional)

Offer once (own message) if visual questions are expected. If accepted, decide per-question whether to use browser vs. terminal based on whether the question would be better understood by seeing vs. reading.

Step 3: Clarifying Questions

Ask one question per message. Refine understanding through Socratic questioning. Explore alternatives and trade-offs.

Step 4: Propose Approaches

Present 2-3 approaches with trade-offs and a recommendation. Get approval after each section.

Step 5: Present Design in Sections

Scale each design section to its complexity. Get explicit approval after each section before proceeding.

Step 6: Write Design Document

Save to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and commit. Include:

• Problem statement
• Proposed approach
• Key decisions and rationale
• File structure
• API contracts (if applicable)

Step 7: Spec Review Loop

Dispatch a spec-document-reviewer subagent to review the written spec. Fix issues. Max 3 iterations, then surface to human for guidance.

Step 8: User Reviews Written Spec

User reviews the written spec before proceeding.

Step 9: Invoke Writing Plans

Terminal state: invoke superpowers-writing-plans — the only skill to invoke at the end.

Anti-Pattern

"This Is Too Simple To Need A Design" — every project goes through this process regardless of perceived simplicity.

Boil the Lake

When presenting approaches or options, always recommend the complete implementation when AI makes the marginal cost near-zero.

Lake vs ocean: A lake is boilable (100% coverage, full feature, all edge cases). An ocean is not (system rewrites, multi-quarter migrations).

Show both effort scales: human time vs AI time.

Compression reference:

Task	Human	AI	Compression
Boilerplate	2 days	15 min	~100x
Tests	1 day	15 min	~50x
Feature	1 week	30 min	~30x
Bug fix	4 hours	15 min	~20x
Architecture	2 days	4 hours	~5x
Research	1 day	3 hours	~3x

Anti-patterns to avoid:

• Recommending shortcuts when complete costs minutes more
• Deferring tests to follow-up PR
• Quoting only human effort ("This would take 2 weeks")

Search Before Building

Before proposing solutions, check what exists. Three layers:

• Layer 1 (tried and true): Standard patterns already in the ecosystem
• Layer 2 (new and popular): Search for current best practices — but scrutinize them
• Layer 3 (first principles): Your original reasoning about the specific problem

When Layer 3 reasoning reveals conventional wisdom is wrong, name it:

EUREKA: Everyone does X because [assumption]. But [evidence] shows Y is better.

Log eureka moments to project memory for future reference.

Integration

• Required sub-skill: superpowers-writing-plans — invoked at the end
• Called by: superpowers-using-superpowers
• Creates: design document at docs/superpowers/specs/