alexei-led/brainstorming-ideas

Brainstorming Ideas

Turn a vague idea or draft plan into a clear design before coding. In grill mode, stress-test a plan until every important branch of the decision tree is resolved.

Use TaskCreate / TaskUpdate to track these 7 phases:

1. Understand the idea (dialogue first, no agents)
2. Explore requirements (Starbursting questions)
3. Checkpoint - offer exploration/research options
4. Research similar solutions (if requested)
5. Present approaches with recommendation
6. Validate design incrementally
7. Capture outcome and next steps

Core Principles

• Dialogue first - Ask the user before spawning any agents
• One question at a time - Never batch multiple questions
• Multiple choice preferred - Easier to answer than open-ended
• "Other" always available - Free text input for custom responses
• YAGNI ruthlessly - Challenge every feature's necessity
• Incremental validation - Present design in 200-300 word sections
• Agents on request - Only explore/research when user chooses it
• Code over questions - If the codebase can answer a question, inspect it instead of asking
• Domain vocabulary matters - Use CONTEXT.md / CONTEXT-MAP.md terms when present; resolve conflicts explicitly
• ADRs are rare - Offer one only for hard-to-reverse, surprising, real trade-off decisions

Phase 0: Load Domain Context

Before asking design questions, check for project knowledge when relevant. Use Glob/Read to find the nearest relevant CONTEXT.md, CONTEXT-MAP.md, and docs/adr/ files. If present, read them and use that vocabulary in questions and designs.

If no domain docs exist, create them lazily only when a term or decision is actually resolved. Do not generate empty documentation.

Phase 1: Understand the Idea

Start with dialogue, not agents. Ask the user directly.

1a. Initial Question

Use AskUserQuestion:

• Idea type — What would you like to brainstorm? Options: 1. New feature - Add new functionality 2. Modification - Change existing behavior 3. Integration - Connect with an external system 4. Plan grill - Stress-test an existing plan 5. Exploration - Not sure yet, let's discover

1b. Follow-up (based on response)

Ask clarifying questions using AskUserQuestion. Keep it conversational:

• "Can you describe this in a sentence or two?" (free text via "Other")
• "What triggered this idea?" with context-appropriate options
• "Is there an existing feature this builds on?"

Phase 2: Explore Requirements (Starbursting)

Ask questions one at a time using AskUserQuestion. Adapt based on idea type.

Question Framework (5WH)

• WHO — Always first; "Who will use this?" → Options: Existing users, New segment, Internal, API consumers
• WHY — After WHO; "What problem does this solve?" → Options based on detected pain points
• WHAT — After WHY is clear; "What's the core capability?" → Open or options based on research
• WHERE — For integrations/modifications; "Where should this live?" → Options based on codebase exploration
• HOW — After approach research; "How should we implement?" → Present 2-3 technical approaches

Adaptive Questioning

• Skip questions when answers are obvious from context
• If user seems certain, move faster to approaches
• If user seems uncertain, explore deeper with sub-questions
• Use "Other" option to allow custom responses

2b. Plan Grill Mode

If the user passed plan, grill, or asked to stress-test/challenge a plan, interrogate the plan one decision at a time. Keep it focused on design quality and assumptions, not task breakdown; use the spec-plan skill for implementation tasks.

For the full interview discipline (phase order, per-question format, final summary, failure handling), read references/grill-protocol.md.

For each question:

• Provide your recommended answer.
• Explain why the branch matters.
• If the answer is discoverable from code, inspect code instead of asking.
• If a term conflicts with CONTEXT.md, call it out: "Your glossary defines X as A, but this plan uses X as B — which is it?"
• Use concrete scenarios and edge cases to force precision.

When a domain term is resolved, confirm before writing and update CONTEXT.md inline if the user approves the wording. Keep definitions one sentence. List aliases to avoid.

Offer an ADR only when all three are true:

1. Hard to reverse.
2. Surprising without context.
3. Result of a real trade-off.

2c. Surface Assumptions

Before moving on, explicitly list the assumptions embedded in the idea so far:

Based on our discussion, here are the assumptions I'm seeing:

1. [Assumption about users] — e.g., "Users want X in real-time"
2. [Assumption about tech] — e.g., "Our current DB can handle this load"
3. [Assumption about scope] — e.g., "This doesn't need to work offline"

Use AskUserQuestion:

• Assumptions — Any of these assumptions wrong or risky? Options: 1. All correct - Proceed as-is 2. Some wrong - I'll clarify 3. Not sure - Let's validate the risky ones during research

If "Some wrong": ask which ones and adjust requirements. If "Not sure": flag risky assumptions for verification in Phase 4.

Phase 3: Checkpoint - Gather More Context?

After understanding requirements, ask before spawning any agents:

• Next step — How should we proceed? Options: 1. Explore codebase - Check existing patterns and tech stack 2. Research solutions - Look up how others solve this 3. Check project history - Query past decisions on this topic (claude-mem) 4. Both - Explore then research 5. Skip to approaches - I know what I want

If user chooses "Explore codebase":

Task(
  subagent_type="Explore",
  prompt="Quick scan: project structure, tech stack, patterns relevant to [user's idea]",
  run_in_background=false
)

Then summarize findings and ask: "Based on this, should we also research external solutions?"

If user chooses "Check project history":

If claude-mem tools are available:

search({ query: "[topic keywords]", limit: 10 })
timeline({ query: "[topic keywords]", depth_before: 5, depth_after: 5 })

Summarize past decisions, known issues, and relevant context. Then ask if they want to also explore or research.

If user chooses "Research solutions":

Proceed to Phase 4.

If user chooses "Skip to approaches":

Jump directly to Phase 5 (Present Approaches).

Failure cases

• If codebase exploration returns no relevant matches: state "no prior implementation found" and proceed to Phase 5 without fabricating patterns.
• If user abandons mid-session: offer to write a partial design note before stopping.

Phase 4: Research Similar Solutions (If Requested)

Only run when user explicitly chose research in Phase 3.

If Perplexity is unavailable: skip to WebFetch with a direct search query; do not fabricate patterns.

4a. Perplexity Query

mcp__perplexity-ask__perplexity_ask({
  messages: [{
    role: "user",
    content: "How do leading [industry] products implement [feature type]? Include architectural patterns, UX approaches, and trade-offs. Focus on [tech stack] implementations."
  }]
})

4b. Follow Citations

After Perplexity response, WebFetch top 2-3 relevant sources:

WebFetch(url="<citation-url>", prompt="Extract implementation details, code patterns, and lessons learned for [feature]")

4c. Synthesize Findings

Present research summary before asking approach preference:

## Research Findings

**Common patterns:**

- [Pattern 1]: Used by X, Y. Trade-off: ...
- [Pattern 2]: Used by Z. Trade-off: ...

**Recommended for our context:** [Pattern] because [reasons]

Phase 5: Present Approaches

Use AskUserQuestion with 2-4 options:

• Approach — Which approach fits best? Options: 1. [Recommended] - Description + key trade-off 2. [Alternative] - Description + key trade-off 3. Minimal - YAGNI version

Approach Template

For each option, briefly cover:

• What: Core implementation
• Trade-offs: Complexity vs flexibility, Now vs later
• Fits when: Scenario where this shines

Phase 6: Validate Design Incrementally

Present design in sections (~200-300 words each). After each section, use AskUserQuestion:

• Validate — Does this [section] look right? Options: 1. Yes, continue - Move to next section 2. Needs changes - I'll explain 3. Go back - Revisit earlier decisions

Design Sections

1. Architecture Overview - Components, responsibilities, relationships
2. Data Flow - How information moves through the system
3. API/Interface - External contracts and user interactions
4. Error Handling - Failure modes and recovery strategies
5. Testing Strategy - How to verify it works

YAGNI Checkpoints

At each section, actively challenge:

• "Do we need this now, or is it speculative?"
• "What's the simplest version that solves the problem?"
• "Can we defer this complexity?"

Phase 7: Capture Outcome and Next Steps

7a. Update Domain Docs Only When Needed

If the brainstorm resolved domain language, update CONTEXT.md or the relevant context file:

## Language

**Term**:
One-sentence definition.
Avoid: fuzzy synonym, overloaded alias

If a qualifying architectural/product decision crystallized, create a short ADR under docs/adr/NNNN-slug.md:

# Decision title

One to three sentences: context, decision, why.

Skip ADRs for easy-to-reverse, obvious, or no-real-alternative decisions.

7b. Write Design Notes If Useful

If the outcome is more than a short answer, offer to write a concise design note:

docs/plans/YYYY-MM-DD-<topic>-design.md

Include only: Problem, Chosen approach, Trade-offs, Open questions, Testing strategy.

7c. Implementation Handoff

Use AskUserQuestion:

• Next steps — Ready to proceed with implementation? Options: 1. Create worktree - Isolated workspace via using-git-worktrees 2. Create plan - Detailed implementation steps 3. Done for now - Just save the design

Failure handling

• Idea conflicts with CONTEXT.md / CONTEXT-MAP.md: surface the contradiction explicitly ("the glossary defines X as A, this idea assumes B"). Resolve the term with the user before designing — do not silently pick one.
• A constraint blocks every approach: stop generating options. State the blocker, what would unblock it, and ask the user to relax the constraint or change scope.
• Idea is too vague to design (user cannot state the problem in one sentence): stay in Phase 1. Ask one narrowing question at a time; do not fabricate requirements or jump to approaches.

Examples

/brainstorming-ideas user notifications # Explore a feature idea
/brainstorming-ideas plan auth flow     # Shape a draft plan
/brainstorming-ideas grill migration    # Stress-test an existing plan

Execute this collaborative brainstorming workflow now