Tutorial Overview

Series index: Superpowers Tutorial Series

brainstorming is one of the most important skills in the Superpowers framework. Its core idea is simple: understand the problem thoroughly before writing any code.

What you will learn

• ✅ When the brainstorming skill triggers
• ✅ The Socratic questioning workflow
• ✅ The structure and storage of design documents
• ✅ Real-world case analysis
• ✅ Common issues and how to handle them

Why Do We Need brainstorming?

Problems with the traditional AI development flow

flowchart LR
    A[User requirement] --> B[AI writes code directly]
    B --> C[Finds out it misunderstood]
    C --> D[Rework and rewrite]
    D --> E[Multiple iterations]
    E --> F[Final completion]
    
    style B fill:#ffcccc
    style C fill:#ffcccc
    style D fill:#ffcccc

The Superpowers flow

flowchart TD
    A[User requirement] --> B[Start `brainstorming`]
    B --> C[Socratic questioning]
    C --> D[Clarify the details]
    D --> E[Generate a chunked design document]
    E --> F[User confirms each chunk]
    F --> G[Start implementation]
    
    style B fill:#e1f5ff
    style E fill:#e1f5ff
    style F fill:#e1f5ff

Comparison

brainstorming Skill Explained

When it triggers

The brainstorming skill automatically triggers in these scenarios:

1. Creating a new feature - “Add a user login feature”
2. Building a component - “Create a navigation bar component”
3. Changing behavior - “Change the article sorting order”
4. Adding an integration - “Integrate Stripe payments”

Core workflow

sequenceDiagram
    participant U as User
    participant AI as AI assistant
    participant D as Design document
    
    U->>AI: I want to add comments
    AI->>AI: Trigger `brainstorming`
    AI->>U: Question 1: Do comments need moderation?
    U->>AI: Yes, review before publishing
    AI->>U: Question 2: Which formats should we support?
    U->>AI: Markdown and code blocks
    AI->>U: Question 3: What user system do we use?
    U->>AI: Use the existing GitHub OAuth
    AI->>D: Generate chunked design document
    D->>U: Chunk 1: Data model design
    U->>AI: Confirm
    D->>U: Chunk 2: API design
    U->>AI: Needs changes...
    AI->>D: Update design
    D->>U: Chunk 3: Frontend components
    U->>AI: Confirm everything
    AI->>AI: Design complete, switch to planning

Socratic Questioning

What is Socratic questioning?

Socratic questioning is a method of guiding thinking through questions. In brainstorming, AI does not assume the answer. Instead, it uses a sequence of questions to:

1. Clarify concepts - “What exactly do you mean by ‘fast’?”
2. Challenge assumptions - “Why choose this approach?”
3. Explore alternatives - “Have you considered another method?”
4. Check consistency - “Does this conflict with the earlier design?”

Typical question types

1. Requirement clarification

• Who is the target user for this feature?
• What core problem does the user need to solve?
• What does "high performance" mean in concrete terms? (QPS? latency?)
• Which edge cases need to be supported?

2. Technical choice

• Why choose Redis instead of Memcached?
• How scalable is this solution?
• Is there a simpler alternative?
• What is the acceptable level of technical debt?

3. Security and risk

• Which authentication mechanisms does this API need?
• How do we prevent abuse or attacks?
• How sensitive is the data? Does it need encryption?
• What is the fallback strategy for failure scenarios?

4. Testing and validation

• How do we verify that this feature is correct?
• Which unit tests are needed?
• What is the strategy for integration tests?
• What are the benchmarks for performance tests?

Design Document Structure

After brainstorming completes, it generates a structured design document that usually contains the following sections:

Standard template

# Feature Name

## 1. Overview

### 1.1 Goal
[The core problem this feature solves]

### 1.2 Scope
[The boundaries of the feature]

### 1.3 Non-goals
[What is explicitly out of scope]

## 2. Requirements

### 2.1 Functional requirements
- [ ] FR1: ...
- [ ] FR2: ...

### 2.2 Non-functional requirements
- [ ] Performance: ...
- [ ] Availability: ...
- [ ] Security: ...

## 3. Design Proposal

### 3.1 Architecture overview
[System architecture diagram]

### 3.2 Data model
[Database schema / data structures]

### 3.3 API design
[Endpoint definitions]

### 3.4 Component design
[Frontend/backend component boundaries]

## 4. Implementation Considerations

### 4.1 Technical choices
[Key decisions and why they were made]

### 4.2 Dependencies
[External and internal dependencies]

### 4.3 Risks and mitigations
[Potential risks and how to address them]

## 5. Testing Strategy

### 5.1 Unit tests
[Core logic that needs coverage]

### 5.2 Integration tests
[System interaction tests]

### 5.3 Performance tests
[Performance benchmarks and test methods]

## 6. Acceptance Criteria

- [ ] All functional requirements implemented
- [ ] Unit test coverage >= 80%
- [ ] Performance targets met
- [ ] Code review passed

Chunked confirmation

The design document is not shown all at once. It is presented in chunks:

Chunk 1: Overview and requirements (wait for confirmation)
    ↓
Chunk 2: Data model and API (wait for confirmation)
    ↓
Chunk 3: Component design and implementation (wait for confirmation)
    ↓
Chunk 4: Testing strategy and acceptance criteria (wait for confirmation)

This approach helps because:

• ✅ It avoids overwhelming the user with too much information
• ✅ Direction changes can be corrected early
• ✅ Each section gets enough discussion

A Real Example

Case: Add a tag system to a blog

Scenario

The user enters:

I want to add tagging to my blog so articles can have multiple tags and users can filter by tag.

Actual conversation flow

Step 1: Initial requirement clarification

AI: Great, I’ll help design the tag system. Before we start, I want to understand a few details:

1. Tag management:
   - Will authors add tags manually?
   - Can users submit tag suggestions?
   - Do we need a tag moderation workflow?

2. Tag characteristics:
   - Are tags hierarchical? (for example: tech/AI/machine learning)
   - Do we need synonym handling? (for example: AI = artificial intelligence)
   - Is there a maximum tag count?

3. Display requirements:
   - Should article list pages show tags?
   - Do we need a tag cloud component?
   - What should the tag page display?

Step 2: Technical choice discussion

User: Tags are flat, with no hierarchy. Authors add them manually, and moderation is not needed.

AI: Understood. For the implementation, I have a few questions:

1. Data storage:
   - What database does the blog use today?
   - Do you prefer relational (MySQL/PostgreSQL) or document-oriented (MongoDB)?

2. Search:
   - Do we only need exact tag matching?
   - Do we need fuzzy search or tag recommendations?

3. SEO:
   - Does each tag need its own URL page?
   - Do we need a tag sitemap?

Step 3: Design document generation

After all questions are answered, AI generates a chunked design document:

[Design Document - Chunk 1: Data Model]

Based on our discussion, here is the data model design:

## Data Model

### articles table (existing)
- id
- title
- content
- created_at

### tags table (new)
- id (PK)
- name (UNIQUE)      # tag name, unique
- slug (UNIQUE)      # SEO-friendly name
- created_at

### article_tags table (new, join table)
- article_id (FK)
- tag_id (FK)
- PRIMARY KEY (article_id, tag_id)

[Confirmation notes]
- Many-to-many relationship: one article can have multiple tags, and one tag can belong to multiple articles
- Tag names are unique to avoid duplicates
- `slug` is used for SEO-friendly URLs

Please confirm whether this design matches your requirements or needs changes.

Step 4: Iteration

User: The tags table also needs a description field for tag notes.

AI: Sure, here is the updated `tags` table:

### tags table (updated)
- id (PK)
- name (UNIQUE)
- slug (UNIQUE)
- description (TEXT, NULLABLE)  # new
- created_at

[Continue with Chunk 2: API design]
...

Step 5: Design complete

After all chunks are confirmed, the design document is saved and ready to move into the planning stage.

Best Practices

Suggestions for the user

1. Answer questions in detail

✅ Good: explain requirements and constraints clearly
❌ Bad: "whatever", "anything is fine"

Example:
✅ "We need to support 1000 QPS and latency under 100ms"
❌ "Performance should be good"

2. State constraints early

- Time constraint: "This feature needs to ship next week"
- Technical constraint: "We can only use the existing MySQL database"
- Resource constraint: "Only I will maintain this, so keep it simple"

3. Challenge design decisions

- "Why choose this approach?"
- "Is there a simpler way to do this?"
- "How extensible is this design?"

Suggestions for AI (through configuration)

1. Set context

brainstorming:
  context:
    project_type: "personal-blog"
    team_size: 1
    tech_stack: ["Hugo", "MySQL"]
    constraints:
      - "No new database"
      - "Must remain compatible with the current theme"

2. Define question depth

brainstorming:
  question_depth: "medium"  # shallow/medium/deep
  # shallow: 3-5 questions
  # medium: 8-12 questions
  # deep: 15+ questions, full design review

3. Configure design document detail

brainstorming:
  design_doc:
    detail_level: "standard"  # minimal/standard/comprehensive
    include_diagrams: true
    include_api_spec: true

Common Questions

Q1: brainstorming is too slow. Can I skip it?

Answer: Skipping it is not recommended, but you can optimize it:

# Rapid prototyping mode
brainstorming:
  mode: rapid
  max_questions: 5
  design_doc: minimal

But remember: time saved up front is often paid back later, with interest.

Q2: What if AI asks questions that are too basic?

Answer: Provide context proactively:

I want to add tagging. Here is the background first:
- Hugo static blog
- MySQL database
- Personal use, QPS < 10
- No comments or user accounts

Given that, can we go straight into the tag design?

Q3: The design document is too long to read

Answer: Ask AI to shorten it:

Please simplify the design document and keep only the core sections. We can discuss details during implementation.

Or configure:

brainstorming:
  design_doc:
    max_length: "2 pages"
    focus_on: ["data_model", "api"]

Q4: AI still writes code after brainstorming

Answer: Check the configuration:

# Make sure enforce_design_first is enabled
superpowers:
  enforce_design_first: true
  require_design_approval: true

Design Document Storage

After brainstorming completes, the design document is stored at:

.project/designs/
└── feature-<name>-<date>.md

For example:

.project/designs/
└── feature-tag-system-2026-02-28.md

You can inspect design history with:

ls .project/designs/
cat .project/designs/feature-tag-system-2026-02-28.md

How It Works with Other Skills

brainstorming -> writing-plans

After the design is confirmed, writing-plans is triggered automatically:

`brainstorming` complete
    ↓
`writing-plans` triggered automatically
    ↓
Atomic implementation tasks generated

brainstorming -> using-git-worktrees

Before implementation starts, worktree creation is triggered automatically:

Ready to start implementation
    ↓
`using-git-worktrees` triggered automatically
    ↓
Isolated development environment created

Summary

The core value of brainstorming is:

1. Force thinking - prevent AI from jumping straight into code
2. Clarify requirements - uncover the real needs through questions
3. Design documents - keep a traceable record of design decisions
4. User confirmation - every step requires your approval

Key takeaways

• ✅ brainstorming triggers before code is written
• ✅ Socratic questioning is the core method
• ✅ Design documents are confirmed in chunks to avoid information overload
• ✅ Design documents are saved so decisions can be traced later

Series navigation:

• ← Previous: Tutorial 1: Superpowers Setup and Installation
• → Next: Tutorial 3: writing-plans - Writing an Implementable Technical Plan
• Back: Series Index