brainstorming-ideas · diff
git:20260602.53635f9 to git:20260603.f0f4806
86 added, 71 removed. Audit B to B.
---
description:
Brainstorm ideas and stress-test draft plans before coding. Use when
brainstorming, exploring approaches, designing a feature/API/flow, grilling or debating
a bounded plan, challenging assumptions, or resolving design-blocking terminology. NOT for
implementation task breakdown; use spec-plan. NOT for generic technology comparisons or
best-practice research; use researching-web. NOT for docs updates; use documenting-code.
name: brainstorming-ideas
---
# Brainstorming Ideas
- Turn a vague idea or draft plan into a well-formed design before coding.
+ Turn a vague idea or draft plan into a well-formed design before coding. Keep the
+ session collaborative, question-driven, and small enough to change direction.
- ## Core principles
+ ## Core rules
- Ask one question at a time.
+ - Use an interactive question tool when available; do not emulate menus in plain text.
- Inspect code before asking when code can answer.
- - Offer 2-3 options with trade-offs; mark one recommendation.
- - Use existing `CONTEXT.md`, `CONTEXT-MAP.md`, and ADR vocabulary.
- - Cut speculative features.
+ - Offer 2-3 options with trade-offs and mark one recommendation.
+ - Always allow a free-text or Other answer when options may not fit.
+ - Cut speculative features and route task breakdown to `spec-plan`.
- ## Step 0: Load domain context
+ ## Interactive questions
+ When a runtime question tool is available, use it for every choice point:
+
+ - single-select for one path, approach, or confirmation
+ - multi-select for multiple goals, risks, constraints, or audiences
+ - free text for problem statements, plan details, or custom answers
+ - options plus Other when you can suggest likely answers but need flexibility
+
+ Do not ask the user to type `1`, `2`, or `3` unless no interactive tool is
+ available. If no tool exists, use concise labeled options and include `Other`.
+
+ ## Load domain context
+
Before design questions, look for relevant project docs:
- `CONTEXT.md`
- `CONTEXT-MAP.md`
- `docs/adr/`
- nearest `*/CONTEXT.md` or `*/docs/adr/`
- Read them when present. Use those terms in questions and designs. If no docs exist, create them only with user approval and only when a real term or decision is resolved.
-
- ## Step 1: Understand the idea
-
- Ask: "What's the idea or plan you'd like to explore?"
-
- Follow up one question at a time:
+ Read them when present. Use those terms in questions and designs. If no docs
+ exist, create them only with user approval and only when a real term or decision
+ is resolved.
- - What pain triggered this?
- - Who uses it?
- - What existing feature does it build on or replace?
- - What is explicitly out of scope?
+ ## Understand the idea
- Stop when you can state the problem in one sentence.
+ If the user did not supply a topic or plan, ask what they want to explore. Then
+ narrow one question at a time until you can state the problem in one sentence.
+ Prefer questions about:
- ## Step 2: Grill or debate a bounded plan when requested
+ - pain or trigger
+ - user or actor
+ - existing feature it builds on or replaces
+ - explicit non-goals
+ - strongest constraint
- Use this mode only for a specific plan or trade-off. If none is clear, ask for one.
+ ## Grill or debate mode
- Read `references/grill-protocol.md` and follow it. Also:
+ Use only for a bounded plan, trade-off, or assumption. If none is clear, ask for
+ one. Read `references/grill-protocol.md` and follow it.
- - Test assumptions with concrete edge cases.
- - Flag vocabulary conflicts with `CONTEXT.md`.
- - If the discussion turns into task breakdown, stop and route to `spec-plan`.
+ Stay focused on design quality and assumptions, not implementation task breakdown.
+ Route task sequencing to `spec-plan`.
- ## Step 3: Surface requirements and assumptions
+ ## Surface requirements and assumptions
- Use 5WH, skipping anything already clear:
+ Use 5WH, skipping what is already clear:
1. WHO uses it?
2. WHY is it needed?
3. WHAT is the core capability?
4. WHERE does it live?
- 5. HOW should it work, if there is a strong constraint?
-
- Then state assumptions explicitly and ask which are wrong.
-
- ## Step 4: Explore the codebase
-
- Find:
-
- - similar modules or flows
- - conventions and testing patterns
- - integration points
- - constraints from ADRs or existing architecture
+ 5. HOW should it work, only when a hard constraint exists?
- Summarize in 3-5 bullets. Use project vocabulary. Cite key paths when code shaped the recommendation.
+ State assumptions explicitly and ask which are wrong or risky. Use multi-select
+ when several assumptions can be wrong.
- ## Step 5: Research external solutions only if requested
+ ## Explore context before solutions
- If the request is only a generic technology comparison or best-practice survey, use `researching-web` instead. Otherwise compare patterns, trade-offs, and common failure modes. Summarize before proposing approaches.
+ Find similar modules, flows, conventions, integration points, test patterns, and
+ architecture constraints. Summarize in 3-5 bullets. Cite key paths when code
+ shaped the recommendation.
- ## Step 6: Propose approaches
+ Research external solutions only if the user asks or selects that path. If the
+ request is only a generic technology comparison or best-practice survey, use
+ `researching-web` instead.
- Present 2-3 options. For each:
+ ## Propose and validate approaches
- - **What**: one-sentence approach
- - **Trade-offs**: complexity vs flexibility
- - **Best when**: scenario where it wins
+ Present 2-3 approaches. For each:
- Mark one as recommended. Ask which fits best.
+ - What: one-sentence approach
+ - Trade-offs: complexity vs flexibility
+ - Best when: scenario where it wins
- ## Step 7: Detail the chosen design
+ Mark one recommendation. Ask which fits best with the interactive question tool.
- Present only relevant ~200-word sections and confirm after each. Typical sections:
+ Then detail the chosen design in short sections, confirming after each:
1. Architecture overview
2. Data flow
3. API or interface
4. Error handling
5. Testing strategy
- Apply YAGNI at each section. Cut speculative pieces.
+ Apply YAGNI at each section. Remove pieces that do not solve the stated problem.
- ## Step 8: Capture outcome
+ ## Capture outcome
If the outcome is more than a short answer, offer to write a concise design note:
```text
docs/plans/YYYY-MM-DD-<topic>-design.md
```
- Include only: Problem, Chosen approach, Trade-offs, Open questions, Testing strategy.
+ Include only Problem, Chosen approach, Trade-offs, Open questions, and Testing strategy.
- If domain terms crystallized, propose a `CONTEXT.md` entry and write it only with user approval:
+ If a domain term crystallized, propose a `CONTEXT.md` entry and write it only with
+ user approval:
```markdown
Term:
One-sentence definition.
Avoid: overloaded synonym
```
- If hard-to-reverse decisions crystallized, offer an ADR only when the decision is surprising without context and came from a real trade-off.
-
- ## Failure handling
+ Offer an ADR only for decisions that are hard to reverse, surprising without
+ context, and came from a real trade-off.
- - 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 Step 1. Ask one narrowing question at a time; do not fabricate requirements or jump to approaches.
- - No bounded plan or trade-off exists for grill/debate mode: ask for one; do not invent opposing positions.
+ ## Output contracts
- ## Output format
+ Completed:
```text
BRAINSTORM COMPLETE
- ===================
Topic: <topic>
- Approach chosen: <name>
- Design note: docs/plans/YYYY-MM-DD-<topic>-design.md or none
-
- Key decisions:
- - <decision>
+ Approach chosen: <name or none>
+ Design note: <path or none>
+ Key decisions: <bullets>
+ Domain docs: <updates or none>
+ Open questions: <bullets or none>
+ ```
- Domain docs:
- - <CONTEXT/ADR updates or none>
+ Paused or routed:
- Open questions:
- - <unresolved>
+ ```text
+ BRAINSTORM PAUSED | ROUTED TO <skill>
+ Topic: <topic>
+ Current state: <one sentence>
+ Resolved: <bullets>
+ Needed next: <question, artifact, or target skill>
```
+
+ ## Failure handling
+
+ - Idea conflicts with domain docs: quote the conflicting terms and resolve with the user before designing.
+ - A constraint blocks every approach: state the blocker, what would unblock it, and ask what to relax.
+ - Idea is too vague: stay in understanding mode; ask one narrowing question at a time.
+ - No bounded plan exists for grill/debate: ask for one; do not invent opposing positions.
+ - User stops mid-session: offer the paused output or a short design note.