brainstorm-design

name	brainstorm-design
description	Run a structured design conversation that explores requirements, proposes 2-3 approaches with tradeoffs, and converges on a validated design BEFORE any code is written — used when a feature/idea is fuzzy or under-specified.
when_to_use	User describes a feature/idea/problem that is vague, open-ended, or has multiple viable approaches; before write-plan or implementation; when 'should I build X or Y' framing appears. Skip for one-line trivial changes (typo, rename, log line).

When to Use

Invoke when the request is a design decision, not a typing task. Concrete triggers:

• The ask is a goal, not a mechanism: "add caching", "make onboarding smoother", "let users export data" — how is undecided.
• "Should I build X or Y?" / "What's the best way to do Z?" framing.
• The change touches ≥2 modules, a public API/schema, or a data model (decisions are expensive to reverse later).
• Success criteria, target users, scale, or constraints are unstated.

Skip (go straight to edit/write-plan) when the diff fits in one sentence: typo, rename, log line, version bump, copy tweak, adding a flag to an existing call. Burning a design round on these annoys the user.

This skill stops at a validated design brief. It never writes implementation code. Hand the brief to write-plan (or implementation) next.

Steps

1. Read the surrounding code first, then ask. Before any questions, grep the repo for the relevant module/feature so questions are informed, not generic. Skip questions the code already answers (existing patterns, current schema, conventions). Asking what you could have read yourself wastes the user's turn.

2. Ask 3-5 narrowing questions in ONE message (not drip-fed one at a time). Cover the axes that actually change the design:

   • Scope / non-goals — what is explicitly out of scope for v1?
   • Users & trigger — who hits this, how often, from where (UI, API, CLI, cron)?
   • Constraints — latency budget, data volume, existing stack/deps you must reuse, deadline, backwards-compat?
   • Success criteria — how do we know it works? (a measurable bar, not "it's good")
   • Failure tolerance — what happens on error/empty/duplicate input — block, retry, or degrade?

   Ask only the axes that are genuinely ambiguous. If the user already pinned scope, don't re-ask it.

3. Propose 2-3 candidate approaches as a tradeoff table. One row per approach, columns: Approach | Effort | Risk | Reversibility | Fit. Approaches must be materially different (e.g. "sync in-request" vs "background queue" vs "precompute on write") — not three flavors of the same thing. Each cell is a short concrete phrase, not a paragraph. If you can only think of one real approach, say so and skip the table — don't invent strawmen to pad to three.

4. Recommend one with 1-2 sentences of reasoning tied to the user's stated constraints from step 2 (e.g. "Given the 'no new infra' constraint, B avoids a queue dep while still meeting the 200ms budget"). Take a position — this is a design partner, not a menu.

5. Probe the chosen approach for edge cases and failure modes before locking it: empty/null input, concurrent writes, partial failure, scale ceiling, security/auth surface, migration of existing data. List the ones that genuinely apply; note how the design handles each or flag it as an open question.

6. Emit the design brief and stop. Exactly these sections, kept tight:

   ## Design Brief: <feature>
   **Problem:** <1-2 sentences — the user-facing need>
   **Chosen approach:** <name + 2-3 sentence mechanism>
   **Why:** <the tradeoff that decided it>
   **Non-goals:** <explicit out-of-scope for this iteration>
   **Edge cases handled:** <bullets>
   **Open questions:** <unresolved decisions needing user input — or "none">
   

   Then hand off: "Ready for write-plan / implementation." Do not start coding.

Common Errors

• Skipping questions and jumping to a table. If you guess the constraints, the "best" approach is best for the wrong problem. Always run step 2 unless the user already pinned every axis.
• Drip-feeding questions one per turn — exhausting and slow. Batch all of them into a single message.
• Three fake approaches. Listing minor variants of one idea to fill the table is noise. Two genuinely distinct options beat three near-duplicates.
• Refusing to recommend ("it depends, here are options"). The user invoked a design partner. Pick one and defend it; they can override.
• Re-asking what's in the repo or in chat. Read the code and the existing message first. Asking about conventions the codebase already demonstrates reads as not having looked.
• Sliding into implementation — pseudocode, function signatures, file edits. The deliverable is a brief, not a diff. Stop at the brief even when the design feels obvious.
• Brief with no non-goals or open questions. "Non-goals" prevents scope creep in the next phase; omitting it is the #1 cause of bloated plans downstream.

Verify

Before declaring the design done, confirm all of:

• Read the relevant existing code/schema (not designing blind).
• User answered the narrowing questions, or explicitly waved them off.
• ≥2 materially distinct approaches were surfaced (or a clear reason only one is viable).
• A single approach is recommended with reasoning tied to a stated constraint.
• Edge cases / failure modes were enumerated and addressed or parked.
• Brief contains all sections including Non-goals and Open questions.
• No implementation code was written — output is the brief, handed to the next phase.

If any box is unchecked, the design is not ready to hand off — finish it before moving on.