brainstorming

Brainstorming Ideas Into Designs

Relies on BDK foundation (STARTUP_INSTRUCTIONS.md) for project context and MCP tool preference.

!python3 ${CLAUDE_PLUGIN_ROOT}/scripts/inject.py --chain ${CLAUDE_PLUGIN_ROOT}/fragments/tool-tiers/explore.chain.json

<!-- INJECT: architecture -->

Transform vague ideas into concrete, validated designs through structured dialogue.

Core Principle: Understand → Explore → Design → Validate → Document

The 7-Phase Workflow

Phase 1: Context Analysis

• [ ] Read project CLAUDE.md and relevant rules
• [ ] Check recent commits (last 5)
• [ ] Decide subagent count based on complexity
• [ ] Use subagents to explore related code (later phases that need follow-up findings should SendMessage(to: "<agentId>", ...) the same explorer instead of re-spawning — see STARTUP "Continuing a Spawned Agent")
• [ ] Note constraints (tech stack, patterns, conventions)

GATE: Complete context analysis before Phase 2.

Phase 2: Requirement Discovery

• [ ] Ask ONE question at a time (never multiple)
• [ ] Use AskUserQuestion with 2-4 options when possible
• [ ] Clarify: problem, users, success criteria, constraints
• [ ] WAIT for answer before proceeding

GATE: Clear success criteria before Phase 3.

Phase 3: Approach Exploration

• [ ] Present 2-3 alternative approaches
• [ ] For each: description, pros, cons, complexity
• [ ] Structural check — if an approach extends an existing branching structure (if-elif chain, switch, handler registry), name the structure and its current branch count. If branches would grow past ~3-4, surface the refactor option (polymorphism, dispatch table, state machine) as an alternative approach — even if not recommended.
• [ ] Lead with recommended option + reasoning

GATE: User selects approach before Phase 4.

Phase 4: Design Presentation

• [ ] Break design into 200-300 word sections:
• Architecture overview
• Key components
• Data flow
• Error handling
• Testing approach
• [ ] Present ONE section at a time
• [ ] After EACH section: "Does this look right so far?"
• [ ] WAIT for validation before next section

GATE: All sections user-approved before Phase 5.

Phase 5: Design Validation

• [ ] Review design against original request
• [ ] Check: solves problem? edge cases? error handling? testing clear?
• [ ] List gaps found
• [ ] Address gaps before proceeding

GATE: No unresolved gaps before Phase 6.

Phase 6: Documentation

• [ ] Create file: .bdk/brainstorming/YYYY-MM-DD-HHMM-<topic>-design.md
• [ ] Include: Problem, Solution, Architecture, Components, Data Flow, Error Handling, Testing
• [ ] Verify file created

See [design-template](references/design-template.md) for full document structure.

# [Feature Name] Design

**Date**: YYYY-MM-DD
**Status**: Draft | Approved | Implemented

> **Implementation Note**: To implement this design, use `/bdk:create-plan` to generate a detailed implementation plan.

## Problem Statement
[2-3 sentences]

## Selected Solution

### Architecture Overview
[high-level description]

### Key Components
[list of components with responsibilities]

### Data Flow
[step-by-step flow]

### Error Handling
[error scenarios and responses]

## Testing Strategy
[unit, integration, edge cases]

GATE: Design document exists, matches approved content.

Phase 7: Implementation Handoff

• [ ] Ask user: "Ready to set up for implementation?"
• [ ] If YES → Use /bdk:create-plan
• [ ] If NO → Clarify what's missing

Key Principles

• One question at a time — No overwhelm
• Multiple choice preferred — Easier to answer
• YAGNI ruthlessly — Simplest solution wins
• Explore alternatives — Always 2-3 approaches first
• Incremental validation — Present in sections, validate each
• No premature implementation — Complete design first

Anti-Patterns

• ❌ Jumping to implementation before design approval
• ❌ Presenting entire design at once
• ❌ Assuming requirements (ask instead)
• ❌ Over-engineering (YAGNI)
• ❌ Asking multiple questions at once