brainstorming

name	brainstorming
description	Use when creating or developing anything, before writing code or implementation plans - refines rough ideas into fully-formed designs through structured Socratic questioning, alternative exploration, and incremental validation

Brainstorming Ideas Into Designs

Overview

Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.

Core principle: Ask questions to understand, explore alternatives, present design incrementally for validation.

Announce skill usage at start of session.

When to Use This Skill

Activate this skill when:

• Request contains "I have an idea for..." or "I want to build..."
• User asks "help me design..." or "what's the best approach for..."
• Requirements are vague or high-level
• Multiple approaches might work
• Before writing any code or implementation plans
• User needs to explore trade-offs between different solutions

When NOT to Use This Skill

Skip brainstorming when:

• Requirements are crystal clear and specific
• Only one obvious approach exists
• User has already designed the solution (just needs implementation)
• Time-sensitive bug fix or urgent production issue
• User explicitly says "just implement it" without questions

Examples of clear requirements (no brainstorming needed):

• "Add a print button to this page"
• "Fix this TypeError on line 42"
• "Update the copyright year to 2025"
• "Change the button color to #FF5733"

The Three-Phase Process

Phase	Key Activities	Tool Usage	Output
1. Understanding	Ask questions (one at a time)	AskUserQuestion for choices	Purpose, constraints, criteria
2. Exploration	Propose 2-3 approaches	AskUserQuestion for approach selection	Architecture options with trade-offs
3. Design Presentation	Present in 200-300 word sections	Open-ended questions	Complete design with validation

Phase 1: Understanding

Goal: Gather purpose, constraints, and success criteria.

Process:

• Check current project state in working directory
• Ask ONE question at a time to refine the idea
• Use AskUserQuestion tool when presenting multiple choice options
• Gather: Purpose, constraints, success criteria

Tool Usage: Use AskUserQuestion for clarifying questions with 2-4 clear options.

Example: "Where should the authentication data be stored?" with options for Session storage, Local storage, Cookies, each with trade-off descriptions.

See references/example-session-auth.md for complete Phase 1 example.

Phase 2: Exploration

Goal: Propose 2-3 different architectural approaches with explicit trade-offs.

Process:

• Propose 2-3 different approaches
• For each: Core architecture, trade-offs, complexity assessment
• Use AskUserQuestion tool to present approaches as structured choices
• Include trade-off comparison table when helpful

Trade-off Format:

Approach	Pros	Cons	Complexity
Option 1	Benefits	Drawbacks	Low/Med/High
Option 2	Benefits	Drawbacks	Low/Med/High
Option 3	Benefits	Drawbacks	Low/Med/High

See references/example-session-dashboard.md for complete Phase 2 example with SSE vs WebSockets vs Polling comparison.

Phase 3: Design Presentation

Goal: Present complete design incrementally, validating each section.

Process:

• Present in 200-300 word sections
• Cover: Architecture, components, data flow, error handling, testing
• Ask after each section: "Does this look right so far?"
• Use open-ended questions to allow freeform feedback

Typical Sections:

1. Architecture overview
2. Component details
3. Data flow
4. Error handling
5. Security considerations
6. Implementation priorities

Validation Pattern: After each section, pause for feedback before proceeding to next section.

Tool Usage Guidelines

Use AskUserQuestion Tool For:

• Phase 1: Clarifying questions with 2-4 clear options
• Phase 2: Architectural approach selection (2-3 alternatives)
• Any decision with distinct, mutually exclusive choices
• When options have clear trade-offs to explain

Benefits:

• Structured presentation of options with descriptions
• Clear trade-off visibility
• Forces explicit choice (prevents vague "maybe both" responses)

Use Open-Ended Questions For:

• Phase 3: Design validation
• When detailed feedback or explanation is needed
• When the user should describe their own requirements
• When structured options would limit creative input

Non-Linear Progression

Flexibility is key. Go backward when needed - don't force linear progression.

Return to Phase 1 when:

• User reveals new constraint during Phase 2 or 3
• Validation shows fundamental gap in requirements
• Something doesn't make sense

Return to Phase 2 when:

• User questions the chosen approach during Phase 3
• New information suggests a different approach would be better

Continue forward when:

• All requirements are clear
• Chosen approach is validated
• No new constraints emerge

Key Principles

Principle	Application
One question at a time	Phase 1: Single question per message, use AskUserQuestion for choices
Structured choices	Use AskUserQuestion tool for 2-4 options with trade-offs
YAGNI ruthlessly	Remove unnecessary features from all designs
Explore alternatives	Always propose 2-3 approaches before settling
Incremental validation	Present design in sections, validate each
Flexible progression	Go backward when needed - flexibility > rigidity

After Brainstorming Completes

Consider these optional next steps:

• Document the design in project's design documentation
• Break down the design into actionable implementation tasks
• Create a git branch or workspace for isolated development

Use templates in assets/design-doc-template.md and assets/decision-matrix-template.md for structured documentation.

Socratic Questioning Templates

Purpose Discovery Questions

Goal: Understand the "why" behind the feature.

• "What problem does this solve for your users?"
• "What happens if we don't build this?"
• "How will success be measured?"
• "Who is the primary user of this feature?"
• "What's the most important outcome?"

Constraint Identification Questions

Goal: Uncover limitations and requirements.

• "Are there performance requirements? (e.g., must load in < 2s)"
• "What's the expected scale? (users, data volume, requests/sec)"
• "Are there compliance requirements? (GDPR, HIPAA, SOC2)"
• "What's the timeline/budget constraint?"
• "What existing systems must this integrate with?"

Trade-Off Exploration Questions

Goal: Make implicit preferences explicit.

• "Would you prefer faster development or better performance?"
• "Is flexibility more important than simplicity?"
• "Should this be user-friendly or developer-friendly?"
• "Optimize for: initial build speed, maintainability, or scalability?"
• "What's more critical: feature completeness or time-to-market?"

Alternative Exploration Questions

Goal: Ensure we consider all viable approaches.

• "What if we didn't build this at all? What's the workaround?"
• "How would [competitor/similar product] solve this?"
• "Could we start with a simpler version? What's the MVP?"
• "What if we had unlimited time/budget? What would we add?"
• "What approaches have you already considered and rejected? Why?"

---

Common Pitfalls to Avoid

Pitfall 1: Asking Too Many Questions Upfront

❌ BAD:
"Before we start, I need to know:
1. What's your tech stack?
2. How many users?
3. What's the budget?
4. What's the timeline?
5. Who's the target audience?
..."

✅ GOOD:
"What problem does this solve for your users?"
[Wait for answer, then ask next most important question]

Why: Information overload prevents conversation flow. Ask one at a time.

Pitfall 2: Proposing Only One Approach

❌ BAD:
"Here's the solution: Use Redis for caching..."

✅ GOOD:
"I see three approaches:
1. Redis (fast, but adds infrastructure)
2. In-memory (simple, but doesn't scale)
3. Database query cache (integrated, but slower)
Which trade-offs matter most?"

Why: Single approach suggests you haven't explored alternatives.

Pitfall 3: Over-Engineering from the Start

❌ BAD:
"Let's use microservices, Kubernetes, Redis, Kafka,
message queues, and a service mesh..."

✅ GOOD:
"For 100 users/day, a monolith with PostgreSQL
is sufficient. We can split services later if needed."

Why: YAGNI (You Aren't Gonna Need It). Start simple, scale when necessary.

Pitfall 4: Ignoring Existing Code/Patterns

❌ BAD:
"Let's rebuild this with a completely different architecture..."

✅ GOOD:
[Read existing code first]
"I see you're using Express + PostgreSQL. Let's extend
that pattern with a new route handler..."

Why: Consistency > novelty. Use existing patterns unless there's a compelling reason to change.

---

Integration with Other Skills

After brainstorming completes, consider:

• architecture-decision-record: Document key architectural decisions made during brainstorming
• design-system-starter: Create design tokens and components if building UI
• api-design-framework: Define API contracts if building backend services
• testing-strategy-builder: Plan testing approach for the designed system
• security-checklist: Review security implications of design choices

Example flow:

1. Brainstorming → Design approach selected
2. Architecture Decision Record → Document "Why we chose approach X"
3. API Design → Define endpoints and contracts
4. Testing Strategy → Plan how to test the implementation

---

Real-World Brainstorming Examples

Example 1: E-commerce Product Recommendation Engine

Phase 1 - Understanding:

• Q: "What problem does this solve?" → A: "Users can't discover relevant products"
• Q: "How many products in catalog?" → A: "50,000+ products"
• Q: "What data do we have?" → A: "Purchase history, browsing history, ratings"

Phase 2 - Exploration:

• Approach 1: Collaborative filtering (similar users, proven approach)
• Approach 2: Content-based filtering (product attributes, simpler) ← CHOSEN
• Approach 3: Hybrid ML model (best results, complex implementation)

Phase 3 - Design:

• Vector embeddings for product descriptions
• PostgreSQL with pgvector extension
• Batch embedding generation nightly
• API endpoint returning top 10 similar products

Result: Simple, fast recommendation system launched in 2 weeks

Example 2: Real-Time Analytics Dashboard

Phase 1 - Understanding:

• Q: "What metrics need to be real-time?" → A: "Active users, revenue, errors"
• Q: "How many concurrent viewers?" → A: "10-50 at peak"
• Q: "Acceptable latency?" → A: "Updates within 5 seconds fine"

Phase 2 - Exploration:

• Approach 1: Server-Sent Events (simple, unidirectional) ← CHOSEN
• Approach 2: WebSockets (complex, bidirectional not needed)
• Approach 3: Polling (wasteful, high server load)

Phase 3 - Design:

• SSE endpoint streaming JSON updates every 3 seconds
• Redis pub/sub for broadcasting to multiple viewers
• Automatic reconnection with exponential backoff
• Chart.js for real-time visualization

Result: Real-time dashboard without WebSocket complexity

Example 3: File Upload Service

Phase 1 - Understanding:

• Q: "What file types?" → A: "Images, PDFs, videos"
• Q: "Max file size?" → A: "100MB per file"
• Q: "Expected volume?" → A: "1000 uploads/day"

Phase 2 - Exploration:

• Approach 1: Direct upload to S3 (fast, S3 costs)
• Approach 2: Server upload then S3 (slower, more control) ← CHOSEN
• Approach 3: Cloudinary (expensive, fully managed)

Phase 3 - Design:

• Multipart upload with progress tracking
• Server-side virus scanning (ClamAV)
• Image optimization and thumbnails (Sharp)
• Store metadata in PostgreSQL, files in S3

Result: Secure upload service with virus scanning and optimization

---

Examples

Complete brainstorming sessions:

• references/example-session-auth.md - Authentication storage design (JWT vs Session vs Cookies)
• references/example-session-dashboard.md - Real-time dashboard design (SSE vs WebSockets vs Polling)

Output templates:

• assets/design-doc-template.md - Structured design document format
• assets/decision-matrix-template.md - Weighted decision comparison format

---

Tips for Effective Brainstorming

1. Read the codebase first - Don't propose changes without understanding existing patterns
2. One question at a time - Conversation flow > information dump
3. Always propose 2-3 alternatives - Shows you've explored options
4. Make trade-offs explicit - "Fast but complex" vs "Slow but simple"
5. Validate incrementally - Don't present 10-page design at once
6. Be ready to backtrack - Non-linear is fine when new info emerges
7. Start simple, scale later - YAGNI ruthlessly
8. Document decisions - Use ADRs for key architectural choices

---

Version: 1.1.0 (December 2025) Status: Production-ready patterns from real-world brainstorming sessions