| name | ss-brainstorming |
| description | Use before creating features, building components, adding functionality, or modifying behavior to explore user intent, requirements, and design before implementation |
Brainstorming Ideas Into Designs
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
Start by understanding the current project context, then choose a mode that fits the work and proceed accordingly.
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until the user has approved a design (or the equivalent One-shot artifact bundle). This applies to EVERY project regardless of perceived simplicity.
Anti-Pattern: "This Is Too Simple To Need A Design"
Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
Modes
There are two modes. Pick one after exploring project context, and propose it to the user.
Standard (default)
Full collaborative flow. Use when the change has multiple components, unclear trade-offs, or the user is describing a problem rather than a solution.
Clarifying questions → propose approaches → present design section-by-section → write design.md → subagent review → user reviews → handoff to ss-writing-plans.
One-shot
Scaffold the full artifact bundle (design.md + plan.md + tasks.md) in a single pass without the back-and-forth question loop, then ask the user to review all three together. Use when:
- The user has already supplied enough context to design and plan without further questions
- The change follows a well-understood pattern (e.g., "add an endpoint like the existing ones")
- The user explicitly asks to skip the conversation ("just scaffold it", "one-shot it")
One-shot still produces a real design.md — it does not skip the design step, it just skips the dialogue around it. The user's review of the written artifacts is the approval gate.
If during scaffolding you discover a real ambiguity that affects the design, stop and ask rather than guessing. One-shot trades dialogue for momentum; it does not trade correctness.
Mode Selection
After exploring project context, you MUST propose a mode with AskUserQuestion and wait for the user's selection before doing anything else. This applies in EVERY harness mode — including Auto Mode, `dontAsk`, `acceptEdits`, and any setting that biases against clarifying questions. Mode Selection is NOT a clarifying question; it is a required handoff that decides which Checklist you follow. Never decide the mode unilaterally, even if the request seems obvious or the user already supplied rich context.
The one exception: the user already named the mode in the invocation. If the arguments passed to this skill explicitly say one-shot / standard (in any casing, alone or inside a longer instruction such as one-shot + subagent develop + worktrees + stacked PRs), that IS the selection — do not ask it back. Echo it in one line (Mode: One-shot, per your invocation.) and go straight to that Checklist. Asking a user to re-pick something they just typed is the exact round-trip this gate is supposed to protect, not cause.
This exception is narrow: it needs the mode named. Rich context, a confident tone, or a detailed requirement list is NOT a mode selection — those still go through the question.
Before proposing the mode: the hidden-decision test
Confident user phrasing is not the same as design-resolvedness. Before you lean toward One-shot, ask yourself one question:
Does the request contain a verb that hides an un-discussed design decision?
- Mutating verbs almost always hide decisions — even when the user sounds certain: merge, split, consolidate, unify, redesign, refactor, extract, reorg, replace. The verb itself is the unresolved design question (how to merge? which contract survives? what gets absorbed?). Default Standard.
- Additive verbs usually do not — add, extend, adopt, apply, enable, scaffold — unless the addition becomes a pattern others will copy (a golden-path endpoint, a first-of-kind auth flow, a reference example). Then it is Standard regardless of file count.
- A small file count does not imply One-shot. A single endpoint can be Standard if its semantics are open. A 25-file change can be One-shot if every item is mechanically prescribed by an external spec.
Other signals that force Standard even when the request feels clear:
- Changes a contract of an existing module (interface, schema, event shape, return type)
- Crosses BE↔FE boundary
- Touches concurrency invariants (locks, leases, queues, retries)
- A strategy decision is still open (how to split? new mechanism? which library?)
One-shot is correct only when all three hold: (a) shape is locked by an external spec / convention / existing pattern, (b) work is single-layer or mechanically prescribed, (c) no existing contract changes.
Run this test silently before formulating your recommendation. Then propose the mode you actually believe fits — do not bias toward One-shot to save round-trips.
Proposing the mode
Propose a mode with AskUserQuestion:
- Standard — Collaborative design flow with clarifying questions (recommended default)
- One-shot — Scaffold design + plan + tasks in one pass, then review together
Lead with the mode you think fits and your reason (e.g., "This looks like a Standard change because the word 'merge' hides an undecided contract — which runner's interface survives."). The user can override.
Checklist
Tasks for each mode. Create todos and complete in order.
Standard
- Explore project context — files, docs, recent commits
- Propose mode — confirm Standard (see Mode Selection)
- Ask the frontier, round by round — every currently-answerable question in one round (see Frontier Rounds); purpose, constraints, success criteria
- Propose 2–3 approaches — with trade-offs and your recommendation
- Present design — in sections scaled to complexity; approval after each section
- Write design doc — create
changes/YYYY-MM-DD-<topic>/; save design.md
- Subagent review — dispatch reviewer with codebase verification (see Subagent Review)
- User reviews written spec — ask user to review before proceeding
- Transition to implementation — invoke
ss-writing-plans, passing the change directory path
One-shot
- Explore project context — files, docs, recent commits
- Propose mode — confirm One-shot (see Mode Selection)
- Scaffold design.md — create
changes/YYYY-MM-DD-<topic>/ and write design.md directly from user-supplied context, in a single pass
- Subagent review — dispatch reviewer with codebase verification (see Subagent Review)
- Invoke ss-writing-plans with One-shot signal — pass the change directory and state
mode: one-shot in the handoff message; ss-writing-plans will generate plan.md and tasks.md without pausing, keeping the pass continuous
- Bundled user review — once all three artifacts exist, ask the user to review them together; revise any of them based on feedback
Process Flow
digraph brainstorming {
"Explore project context" [shape=box];
"Propose mode" [shape=diamond];
"Ask the frontier round" [shape=box];
"Frontier empty?" [shape=diamond];
"Propose 2-3 approaches" [shape=box];
"Present design sections" [shape=box];
"User approves design?" [shape=diamond];
"Write design doc (Standard)" [shape=box];
"Scaffold design doc (One-shot)" [shape=box];
"Subagent review" [shape=box];
"User reviews artifacts" [shape=diamond];
"Invoke ss-writing-plans" [shape=doublecircle];
"Explore project context" -> "Propose mode";
"Propose mode" -> "Ask the frontier round" [label="Standard"];
"Propose mode" -> "Scaffold design doc (One-shot)" [label="One-shot"];
"Ask the frontier round" -> "Frontier empty?";
"Frontier empty?" -> "Ask the frontier round" [label="no, recompute"];
"Frontier empty?" -> "Propose 2-3 approaches" [label="yes"];
"Propose 2-3 approaches" -> "Present design sections";
"Present design sections" -> "User approves design?";
"User approves design?" -> "Present design sections" [label="no, revise"];
"User approves design?" -> "Write design doc (Standard)" [label="yes"];
"Write design doc (Standard)" -> "Subagent review";
"Scaffold design doc (One-shot)" -> "Subagent review";
"Subagent review" -> "User reviews artifacts";
"User reviews artifacts" -> "Write design doc (Standard)" [label="changes (Standard)"];
"User reviews artifacts" -> "Scaffold design doc (One-shot)" [label="changes (One-shot)"];
"User reviews artifacts" -> "Invoke ss-writing-plans" [label="approved"];
}
The terminal state is invoking ss-writing-plans. Do NOT invoke frontend-design, mcp-builder, or any other implementation skill from ss-brainstorming.
Frontier Rounds
Standard mode's questioning is a design tree: every decision branches into the decisions that hang off it. The frontier is every decision whose prerequisites are already settled — the questions you can ask now without guessing at answers you haven't heard yet.
Work the tree in rounds. Ask the whole frontier in one round, then wait. The user's answers push the frontier outward and unblock the questions that depended on them; recompute it and ask the next round. A question whose answer depends on another question still open in this round belongs to a later round, not this one. You are done when the frontier is empty — every branch visited, nothing silently assumed.
One question per message is not caution, it is latency: it costs a round-trip per question when the dependency structure only demands one per level of the tree. Dumping every question at once is the opposite failure — it makes the user answer questions whose premises are still open. The frontier is the line between the two.
Asking a round with AskUserQuestion
Every frontier question goes through AskUserQuestion. The tool takes at most 4 questions per call, with 2–4 options each, so a frontier wider than four is several calls back to back — still one round, just more than one card.
- Lead with your recommendation. Put it first, suffix the label with
(Recommended), and give the reasoning in that option's description. A batched question with no recommended answer degrades into a questionnaire — it hands the user the design work you were supposed to have done.
- A genuinely open-ended question (no discrete options worth listing) falls back to prose, in the same message as the round's tool calls.
- Never ask the user to type A, B, C.
Finding facts is your job, never the user's
When a frontier question needs a fact from the environment — an existing pattern, who calls what, the shape of a schema, whether a dependency is already there — dispatch a subagent to find it. Never ask the user for something you could look up.
Don't block on it either. A running exploration is just another unsettled prerequisite: only the questions downstream of that fact wait for it. Ask the rest of the frontier now and fold the finding into the next round.
The decisions are the user's. The facts are yours.
The Process
Understanding the idea:
- Check out the current project state first (files, docs, recent commits)
- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
- For appropriately-scoped projects, work the design tree in frontier rounds (see Frontier Rounds) — one round per level of the tree, not one question per message
- Every question goes through the AskUserQuestion tool with your recommended answer as the first option; never ask the user to type A, B, C
- Look a fact up yourself before you spend a question on it (see Finding facts is your job)
- Focus on understanding: purpose, constraints, success criteria
Exploring approaches:
- Propose 2-3 different approaches with trade-offs
- Present options conversationally with your recommendation and reasoning
- Lead with your recommended option and explain why
Presenting the design:
- Once you believe you understand what you're building, present the design
- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
- Ask after each section whether it looks right so far
- Cover: architecture, components, data flow, error handling, testing
- Be ready to go back and clarify if something doesn't make sense
Design for isolation and clarity:
- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
Working in existing codebases:
- Explore the current structure before proposing changes. Follow existing patterns.
- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
After the Design
Documentation (Standard):
- Create the change directory:
changes/YYYY-MM-DD-<topic>/
- One batch, one directory. Never write into, extend, or recycle a previous batch's change directory, even when the topic overlaps — a finished packet is a record of what shipped, and editing it destroys that. If the new work supersedes an earlier design, say so in the new
design.md and link the old one.
- Write the validated design (spec) to
changes/YYYY-MM-DD-<topic>/design.md
- (User preferences for spec location override this default)
- Use elements-of-style:writing-clearly-and-concisely skill if available
Documentation (One-shot):
- Create
changes/YYYY-MM-DD-<topic>/ and write design.md in a single pass from the user's supplied context. Don't ask questions you can reasonably infer answers to; do stop and ask if you hit a genuine ambiguity.
Subagent Review
After writing design.md, dispatch a general-purpose subagent to review it with fresh eyes. Inline self-review is not acceptable — empirically the author rubber-stamps their own work and skips codebase verification. The reviewer must open the repo to verify concrete claims (file paths, symbol names, fixtures, signatures, counts).
Use the template at spec-document-reviewer-prompt.md. Pass the absolute path of design.md and a short summary of the user's request.
When the subagent returns:
- Approved with no issues → proceed to user review gate.
- Issues found → fix each one (or, for an issue where you disagree, note your reasoning in
design.md so the user can adjudicate), then re-dispatch the reviewer on the updated file. Loop until approved.
Calibration: the reviewer is instructed to flag only issues that would cause real problems during planning or implementation. Minor wording is not an issue.
User Review Gate
Standard: after subagent review, ask the user to review the spec:
"Spec written to /abs/path/to/changes/YYYY-MM-DD-<topic>/design.md. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
Quote the absolute path, not the repo-relative one — the user may be reading from another terminal, another worktree, or a different repo than the one you are in.
Wait for the user. If they request changes, make them and re-run the subagent review. Only proceed once approved.
One-shot: the user review is bundled — review only happens after design.md, plan.md, and tasks.md are all written. Ask:
"All three artifacts written: design.md, plan.md, tasks.md under /abs/path/to/changes/YYYY-MM-DD-<topic>/. Please review them together and let me know if you want changes to any of them."
Revise any of the three based on feedback, then re-run subagent review on whatever changed.
Implementation Handoff
- Invoke the ss-writing-plans skill to create the implementation plan
- Do NOT invoke any other skill. ss-writing-plans is the next step.
Key Principles
- One round at a time — Ask the whole frontier, then wait; never one question per message
- Always recommend — Every AskUserQuestion option set leads with your recommended answer and its reasoning
- Facts are yours, decisions are theirs — Dispatch a subagent for anything you could look up
- YAGNI ruthlessly — Remove unnecessary features from all designs
- Explore alternatives — Always propose 2-3 approaches before settling (Standard mode)
- Incremental validation — Present design, get approval before moving on (Standard); bundle review at the end (One-shot)
- Be flexible — Go back and clarify when something doesn't make sense
Visuals
For visual content (mockups, wireframes, architecture diagrams, layout comparisons), use ASCII diagrams inline in the conversation. They render reliably across every harness, cost nothing in infrastructure, and are sufficient for the level of fidelity brainstorming needs. If the user asks for richer visuals, suggest they sketch in their tool of choice and paste / link images back into the conversation.
