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