rbozydar/brainstorming

Brainstorming

Clarify WHAT to build before diving into HOW to build it.

When to Use

Brainstorm when:

• Requirements are unclear or ambiguous
• Multiple approaches could solve the problem
• Trade-offs need exploration
• Feature scope needs refinement

Skip when:

• Requirements include acceptance criteria
• Task is a straightforward bug fix
• User says "just do it" or provides a detailed spec
• User references a specific existing pattern

Core Process

Phase 0: Assess Requirement Clarity

Before diving into questions, assess whether brainstorming is needed.

Clear requirements signals: specific acceptance criteria, referenced patterns, exact expected behavior, constrained scope.

Brainstorming needed signals: vague terms ("make it better"), multiple interpretations, undiscussed trade-offs.

If requirements are clear, suggest proceeding directly to planning or implementation.

Phase 1: Understand the Idea

Ask questions one at a time to understand intent. Avoid overwhelming with multiple questions.

Question techniques:

1. Prefer multiple choice -- "Should notifications be: (a) email, (b) in-app, or (c) both?"
2. Start broad, then narrow -- core purpose → users → constraints
3. Validate assumptions explicitly -- "Assuming users are logged in. Correct?"
4. Ask about success criteria early -- "How will success be measured?"

Key topics: Purpose/motivation, Users/context, Constraints/timeline, Success criteria, Edge cases, Existing patterns in the codebase.

Exit condition: Continue until the idea is clear OR user says "proceed."

Phase 2: Explore Approaches

Propose 2-3 concrete approaches:

### Approach A: [Name]
[2-3 sentence description]

**Pros:** [Benefits]
**Cons:** [Drawbacks]
**Best when:** [Circumstances]

Lead with a recommendation. Be honest about trade-offs. Consider YAGNI -- simpler is usually better.

Phase 3: Capture the Design

Summarize key decisions:

---
date: YYYY-MM-DD
topic: <kebab-case-topic>
---

# <Topic Title>

## What We're Building
[1-2 paragraphs]

## Why This Approach
[Approaches considered and rationale]

## Key Decisions
- [Decision]: [Rationale]

## Open Questions
- [Unresolved questions]

## Next Steps
→ `/workflows:plan` for implementation details

Output location: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md

Phase 4: Handoff

Present options:

1. Proceed to planning -- run /workflows:plan
2. Refine further -- continue exploring
3. Done for now -- return later

YAGNI Principles

• Do not design for hypothetical future requirements
• Choose the simplest approach that solves the stated problem
• Prefer boring, proven patterns over clever solutions
• Defer decisions that do not need to be made now

Incremental Validation

Keep sections short (200-300 words max). After each section, pause to validate: "Does this match what you had in mind?" This prevents wasted effort on misaligned designs.

Exploration vs Convergence

Exploration mode (divergent): Generate many options without judgment. Use when requirements are unclear or early in brainstorming. Challenge assumptions, consider radical alternatives. Use the gemini-brainstorm agent for external perspectives and the devils-advocate-brainstormer agent to stress-test emerging ideas.

Convergence mode (focused): Narrow to a decision. Use when options are clear and trade-offs understood. Compare against success criteria, apply constraints as filters.

Always confirm mode transitions with the user.

Anti-Patterns

| Anti-Pattern | Better Approach | |--------------|-----------------| | Asking 5 questions at once | Ask one at a time | | Jumping to implementation | Stay focused on WHAT, not HOW | | Overly complex solutions | Start simple, add complexity only if needed | | Ignoring codebase patterns | Research what exists first | | Assumptions without validation | State and confirm assumptions | | Lengthy design documents | Keep concise -- details go in the plan | | Skipping success criteria | Ask early how success will be measured | | Anchoring on first solution | Present 2-3 options before recommending |

Integration with Planning

Brainstorming answers WHAT -- requirements, chosen approach, key decisions. Planning answers HOW -- implementation steps, code patterns, testing strategy.

When brainstorm output exists, /workflows:plan should detect it and use it as input.