Brainstorming Ideas Into Designs

Overview

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

Core principle: Ask questions to understand, explore alternatives, present design incrementally for validation, and research existing codebase patterns.

Announce at start: "I'm using the brainstorming skill to refine your idea into a design."

Codebase Integration

Serena MCP (Understanding Code Patterns)

Before proposing architectural approaches, use Serena to understand how similar features are implemented in the codebase:

1. Early exploration (Phase 1): Use Serena to explore existing patterns that might influence design constraints

   • Example: If brainstorming authentication, check how auth is currently handled
   • Use find_symbol to find authentication-related code
   • Use search_for_pattern for similar implementations

2. Approach evaluation (Phase 2): Reference existing patterns when proposing alternatives

   • Say: "I found that the codebase currently uses [pattern], so approach 1 would align with existing conventions"
   • Use patterns you discover to make recommendations more grounded

3. Design grounding (Phase 3): When presenting the design, reference how it integrates with existing codebase

   • Reference specific files and existing patterns
   • Use find_referencing_symbols to understand dependencies

When to use Serena:

• For existing projects with established patterns
• When design should align with current architecture
• When you need to understand constraints from how code is structured
• When brainstorming involves integrating with existing systems

Graphiti MCP (Contextual Knowledge)

Use Graphiti to enrich understanding of business context, entity relationships, and learned patterns:

1. Context gathering (Phase 1): Search Graphiti for relevant business context

   • Example: "What patterns exist around user authentication in this business context?"
   • Use search_memory_nodes and search_memory_facts to find relevant entities and relationships

2. Alternative grounding (Phase 2): When proposing approaches, reference knowledge about similar past decisions

   • Say: "Based on [previous project/decision], we should consider..."
   • Use graph memory to reference past successful patterns

3. Design enrichment (Phase 3): Ensure design aligns with established business rules and patterns

   • Use graph memory to validate that design respects known constraints
   • Reference discovered relationships between entities

When to use Graphiti:

• For business logic design (tax, financial, compliance features)
• When design needs to respect established patterns
• When understanding multi-entity relationships
• When brainstorming touches learned business rules

Note: If you encounter "stale connection" errors with Graphiti, continue with available information and note the limitation.

Quick Reference

The Process

Copy this checklist to track progress:

Brainstorming Progress:
- [ ] Phase 1: Understanding (purpose, constraints, criteria gathered)
- [ ] Phase 2: Exploration (2-3 approaches proposed and evaluated)
- [ ] Phase 3: Design Presentation (design validated in sections)
- [ ] Phase 4: Design Documentation (design written to docs/plans/)
- [ ] Phase 5: Worktree Setup (if implementing)
- [ ] Phase 6: Planning Handoff (if implementing)

Phase 1: Understanding

• Check current project state in working directory
• Use Serena to explore existing patterns in the codebase (if applicable)
• Use Graphiti to gather business context and understand established patterns
• Ask ONE question at a time to refine the idea
• Use AskUserQuestion tool when you have multiple choice options
• Gather: Purpose, constraints, success criteria

Example with Serena integration:

User: "We need to add real-time notifications to the system"

Claude: Let me first explore how notifications are currently handled in the codebase...
[Uses Serena: find_symbol for "notification", find_referencing_symbols]

I found that notifications are currently handled through [existing pattern].
This means we should consider:
- Whether to extend the existing pattern or create a new approach
- Dependencies on the current notification system
- Current notification types in use

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)

Phase 2: Exploration

• Use Serena to understand existing architectural patterns in the codebase
• Propose 2-3 different approaches grounded in what you discovered
• For each: Core architecture, trade-offs, complexity assessment
• Reference existing patterns from the codebase in your proposals
• Use AskUserQuestion tool to present approaches as structured choices
• Ask your human partner which approach resonates

Example with codebase grounding:

Based on exploring the codebase, I found that [system X] uses [pattern].

Approach 1: Extend pattern used in [system X]
- Pros: Consistent with existing architecture, team familiar
- Cons: May not be optimal for this use case
- Alignment: High - uses established patterns

Approach 2: New pattern optimized for real-time
- Pros: Tailored for requirements, modern architecture
- Cons: New pattern team needs to learn, potential inconsistency
- Alignment: Low - introduces new pattern

Approach 3: Hybrid - adapt [pattern from X] with [technique from Y]
- Pros: Leverages familiar pattern, adds optimizations
- Cons: Moderate complexity, blends two approaches
- Alignment: Medium - extends existing pattern thoughtfully

Example using AskUserQuestion:

Question: "Which architectural approach should we use?"
Options:
  - "Event-driven with message queue" (scalable, complex setup, eventual consistency)
  - "Direct API calls with retry logic" (simple, synchronous, easier to debug)
  - "Hybrid with background jobs" (balanced, moderate complexity, best of both)

Phase 3: Design Presentation

• Present in 200-300 word sections
• Cover: Architecture, components, data flow, error handling, testing
• Reference specific files and patterns discovered from Serena
• Include codebase integration points - how this design connects to existing systems
• Ask after each section: "Does this look right so far?" (open-ended)
• Use open-ended questions here to allow freeform feedback

When presenting design sections, include:

• "In our codebase, this integrates with [file/module] because..."
• "We're leveraging the existing [pattern] from [file] for [reason]"
• "This extends the [existing feature] in [location] by..."
• "The data flow follows our established pattern used in [similar feature]"

Phase 4: Design Documentation

After design is validated, write it to a permanent document:

• File location: docs/plans/YYYY-MM-DD-<topic>-design.md (use actual date and descriptive topic)
• RECOMMENDED SUB-SKILL: Use elements-of-style:writing-clearly-and-concisely (if available) for documentation quality
• Content: Capture the design as discussed and validated in Phase 3, organized into the sections that emerged from the conversation
• Commit the design document to git before proceeding

Phase 5: Worktree Setup (for implementation)

When design is approved and implementation will follow:

• Announce: "I'm using the using-git-worktrees skill to set up an isolated workspace."
• REQUIRED SUB-SKILL: Use superpowers:using-git-worktrees
• Follow that skill's process for directory selection, safety verification, and setup
• Return here when worktree ready

Phase 6: Planning Handoff

Ask: "Ready to create the implementation plan?"

When your human partner confirms (any affirmative response):

• Announce: "I'm using the writing-plans skill to create the implementation plan."
• REQUIRED SUB-SKILL: Use superpowers:writing-plans
• Create detailed plan in the worktree

Question Patterns

When to Use AskUserQuestion Tool

Use AskUserQuestion 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 for partner
• Forces explicit choice (prevents vague "maybe both" responses)

When to Use Open-Ended Questions

Use open-ended questions for:

• Phase 3: Design validation ("Does this look right so far?")
• When you need detailed feedback or explanation
• When partner should describe their own requirements
• When structured options would limit creative input

Example decision flow:

• "What authentication method?" → Use AskUserQuestion (2-4 options)
• "Does this design handle your use case?" → Open-ended (validation)

When to Revisit Earlier Phases

digraph revisit_phases {
    rankdir=LR;
    "New constraint revealed?" [shape=diamond];
    "Partner questions approach?" [shape=diamond];
    "Requirements unclear?" [shape=diamond];
    "Return to Phase 1" [shape=box, style=filled, fillcolor="#ffcccc"];
    "Return to Phase 2" [shape=box, style=filled, fillcolor="#ffffcc"];
    "Continue forward" [shape=box, style=filled, fillcolor="#ccffcc"];

    "New constraint revealed?" -> "Return to Phase 1" [label="yes"];
    "New constraint revealed?" -> "Partner questions approach?" [label="no"];
    "Partner questions approach?" -> "Return to Phase 2" [label="yes"];
    "Partner questions approach?" -> "Requirements unclear?" [label="no"];
    "Requirements unclear?" -> "Return to Phase 1" [label="yes"];
    "Requirements unclear?" -> "Continue forward" [label="no"];
}

You can and should go backward when:

• Partner reveals new constraint during Phase 2 or 3 → Return to Phase 1
• Validation shows fundamental gap in requirements → Return to Phase 1
• Partner questions approach during Phase 3 → Return to Phase 2
• Something doesn't make sense → Go back and clarify

Don't force forward linearly when going backward would give better results.

Key Principles