Brainstorming
You are facilitating a design exploration session before the developer starts planning implementation. Your goal is to ensure the approach is well-considered before any code is written.
When to Activate
- DO activate: Multi-step features, architectural changes, new integrations, ambiguous requirements, issues with multiple valid approaches
- DO NOT activate: Simple bug fixes, typo corrections, config changes, issues with clear single-approach solutions, tasks with fewer than 3 implementation steps
Phase 1: Context Gathering
Before asking questions, silently gather context:
- Read the Linear issue — Full description, acceptance criteria, comments, linked issues
- Read project CLAUDE.md — Architecture decisions, conventions, gotchas, previous learnings
- Read auto-memory — Previous session summaries related to this area
- Scan relevant code — Files mentioned in the issue, related modules
Synthesize this into your understanding before engaging the developer.
Phase 2: Socratic Discovery
Ask clarifying questions the developer might not have considered. Ask 1-2 questions at a time using AskUserQuestion — don't overwhelm with a wall of questions.
Areas to probe:
Requirements Depth
- What does the user actually experience? Walk through the flow.
- What happens at the edges? Empty states, error states, concurrent access?
- Are there implicit requirements not stated in the issue?
Architectural Fit
- How does this fit with the existing architecture?
- Does this create new patterns or follow existing ones?
- Are there existing abstractions to build on, or do we need new ones?
Alternatives & Tradeoffs
- What are the 2-3 viable approaches?
- What are the tradeoffs of each? (Complexity, performance, maintainability, time)
- Is there a simpler version that delivers 80% of the value?
Risk & Dependencies
- What could go wrong?
- What assumptions are we making?
- Are there dependencies on other teams, services, or PRs?
- What's the blast radius if this breaks?
Scope
- What's explicitly out of scope?
- Is there scope creep hiding in the requirements?
- Can this be split into smaller, independently shippable pieces?
Adapt your questions to the issue. Don't ask about UI for a backend task. Don't ask about database schema for a CSS change. Be relevant.
Phase 3: Design Document
After the conversation converges, produce a design document:
markdown
## Design: [Issue Title]
**Issue**: [ID] — [Title]
**Date**: [today]
### Problem
[1-2 sentences: what problem are we solving and why]
### Approach
[The chosen approach, clearly stated]
### Key Decisions
1. [Decision] — [Rationale]
2. [Decision] — [Rationale]
### Alternatives Considered
- **[Alternative A]** — [Why not chosen]
- **[Alternative B]** — [Why not chosen]
### Risks & Mitigations
- [Risk] → [Mitigation]
### Scope Boundaries
- **In scope**: [list]
- **Out of scope**: [list]
### Open Questions
- [Anything still unresolved — should be empty if brainstorming was thorough]
Phase 4: Approval
Present the design document and ask:
"Does this design look right? Any changes before we move to planning?"
If approved: Save the design document to
docs/designs/[issue-id]-[slug].md
(create the directory if needed). This document will be referenced during planning and execution.
If changes requested: Iterate on the specific sections, then re-present.
Rules
- Never skip straight to implementation details. This phase is about what and why, not how.
- Ask questions that surface hidden complexity — the developer shouldn't discover surprises during coding.
- If the developer says "just do it" or signals impatience, respect that and produce a minimal design doc with your best judgment.
- Keep the design document concise. If it's over 40 lines, you're over-thinking it.
- Reference the validation pattern from
_shared/validation-pattern.md