brainstorming

What this skill does

# 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 at start:** "I'm using the brainstorming skill to refine your idea into a design."

## Quick Reference

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

## The Process

**REQUIRED: Create task tracker at start**

Use TaskCreate to create todos for each phase (or TodoWrite in older Claude Code versions):

- Phase 1: Understanding (purpose, constraints, criteria gathered)
- Phase 2: Exploration (2-3 approaches proposed and evaluated)
- Phase 3: Design Presentation (design validated in sections)

Use TaskUpdate to mark each phase as in_progress when working on it, completed when finished (or TodoWrite in older versions).

## Research Agents

**DO NOT perform deep research yourself. Delegate to specialized agents.**

### When to Use codebase-investigator

**Use codebase-investigator when you need to:**
- Understand how existing features are implemented
- Find where specific functionality lives in the codebase
- Identify existing patterns to follow
- Verify assumptions about codebase structure
- Check if a feature already exists

**Example delegation:**
```
Question: "How is authentication currently implemented?"
Action: Dispatch codebase-investigator with: "Find authentication implementation, including file locations, patterns used, and dependencies"
```

### When to Use internet-researcher

**Use @agent-ed3d-research-agents:internet-researcher when available. Otherwise use WebSearch/WebFetch aggressively.**

**Use internet research when you need to:**
- Find current API documentation for external services
- Research library capabilities and best practices
- Compare technology options
- Understand current community recommendations
- Find code examples and patterns from documentation
- Verify "what's the latest version" type questions
- Look up "how do people solve X" patterns

**Example delegation (with agent):**
```
Question: "What's the recommended way to handle file uploads with this framework?"
Action: Dispatch internet-researcher with: "Find current best practices for file uploads in [framework], including official docs and common patterns"
```

**Example without agent (use WebSearch):**
```
Question: "What's the current Stripe API for subscriptions?"
Action: Use WebSearch for: "Stripe subscriptions API latest version 2025"
Then use WebFetch to read the official docs
```

**When to use internet research:**
- External API documentation (always get latest)
- "How do people solve X?" (community patterns)
- Library comparison (which one is maintained?)
- Best practices (what's current recommendation?)
- Version checking (what's latest?)

**Don't overdo it:**
- Don't research things Claude already knows well
- Don't research project-specific code (use codebase-investigator)
- Don't research for every small decision

**Balance:** Use research for external knowledge and current information. Use Claude's existing knowledge for general programming concepts.

### Research Protocol

**If codebase pattern exists:**
1. Use codebase-investigator to find it
2. Unless pattern is clearly unwise, assume it's the correct approach
3. Design should follow existing patterns for consistency

**If no codebase pattern exists:**
1. Use internet research to find external patterns
2. Present 2-3 approaches from research in Phase 2
3. Let user choose which pattern to adopt

**If agent/research can't find answer:**
- Redirect question to user via AskUserQuestion
- Explain what was searched and not found
- Present as a design decision for user to make

**Be persistent with research:**
- If first query doesn't yield results, refine the question
- Try alternative search terms or approaches
- Don't give up after one attempt

## Phase 1: Understanding

**Before asking questions:**

1. **Investigate current state** - DON'T do this yourself:
   - Dispatch codebase-investigator to verify project structure
   - Ask investigator to find existing architecture and patterns
   - Ask investigator to identify constraints from current codebase
   - Review investigator's findings before proceeding

2. **Then gather requirements:**
   - Use TaskUpdate to mark Phase 1 as in_progress
   - Ask ONE question at a time to refine the idea
   - **Use AskUserQuestion tool** when you have multiple choice options
   - **Use agents** when you need to verify technical information
   - Gather: Purpose, constraints, success criteria
   - Mark Phase 1 as completed when understanding is clear

**Example using AskUserQuestion:**
```
Question: "Where should the authentication data be stored?"
Options:
  - "Session storage" (clears on tab close, more secure)
  - "Local storage" (persists across sessions, more convenient)
  - "Cookies" (works with SSR, compatible with older approach)
```

**When to delegate vs ask user:**
- "Where is auth implemented?" -> codebase-investigator
- "What auth library should we use?" -> internet-researcher (if not in codebase)
- "Do you want JWT or sessions?" -> AskUserQuestion (design decision)

**Ask only useful, coherent, and effective questions:**
Do not ask a question when only one answer is useful, coherent, and effective. For example, in an auth system with magic links and social logins:

```
Example (WRONG):
What should happen when a logged-in user requests a magic link for their own email address?

1. Send new magic link (allow re-login)
   User can request magic links even when logged in. Useful for re-authentication or session refresh scenarios.
2. Return error or redirect to home
   Logged-in users can't request magic links. They must log out first. Simpler, prevents confusion.
3. Silent success (no email sent)
   Say 'check your email' but don't send anything. Prevents leaking login state but may confuse legitimate users.
```

In this case, only #1 is a useful, coherent, and effective option. Option #2 doesn't make any sense (magic links can be used to verify emails after a social login) and #3 is aggressively bad (lies to the user).

```
Example (WRONG):
How should the magic link token verification be structured?

1. Single-use token with immediate session creation
   Token is consumed on first click, session created immediately. Simple flow. User can't re-click the link. Standard pattern for passwordless auth.
2. Token valid for multiple users within TTL
   Token can be used multiple times within 15 minutes. Allows re-clicking link if session cookie is lost. More complex state management.
3. Token with idempotent verification
   First use creates session, subsequent uses within TTL return same session. Safe re-clicking, prevents double-session creation. Moderate complexity.
```

No reasonably secure system would do either options #2 or #3. The way this question is written obviously indicates one acceptable answer and the other two answers are trap answers. Do not suggest trap answers for human users.

**If you want to ask a question where there is only one useful, coherent, and effective path, state your assumption and continue onward.**

**Do not ask questions just to ask them. If you have no useful, coherent, and effective questions, cease asking questions.**

**If starting-a-design-plan already gathered context:**
- Phase 1 may be very short
- Focus on remaining unknowns
- Don't re-ask questions already answered in clarification
- St