From superspec
Use before creating features, building components, adding functionality, or modifying behavior to explore user intent, requirements, and design before implementation
How this skill is triggered — by the user, by Claude, or both
Slash command
/superspec:ss-brainstormingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
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.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.
There are two modes. Pick one after exploring project context, and propose it to the user.
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.
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:
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.
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?
Other signals that force Standard even when the request feels clear:
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.
Propose a mode with AskUserQuestion:
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.
Tasks for each mode. Create todos and complete in order.
changes/YYYY-MM-DD-<topic>/; save design.mdss-writing-plans, passing the change directory pathchanges/YYYY-MM-DD-<topic>/ and write design.md directly from user-supplied context, in a single passmode: one-shot in the handoff message; ss-writing-plans will generate plan.md and tasks.md and skip its execution-mode prompt (defaults to Subagent-Driven), keeping the pass continuousdigraph brainstorming {
"Explore project context" [shape=box];
"Propose mode" [shape=diamond];
"Ask clarifying questions" [shape=box];
"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 clarifying questions" [label="Standard"];
"Propose mode" -> "Scaffold design doc (One-shot)" [label="One-shot"];
"Ask clarifying questions" -> "Propose 2-3 approaches";
"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.
Understanding the idea:
Exploring approaches:
Presenting the design:
Design for isolation and clarity:
Working in existing codebases:
Documentation (Standard):
changes/YYYY-MM-DD-<topic>/changes/YYYY-MM-DD-<topic>/design.md
Documentation (One-shot):
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.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:
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.
Standard: after subagent review, ask the user to review the spec:
"Spec written 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."
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.mdunderchanges/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.
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.
npx claudepluginhub coyoteleo/superspec --plugin superspecGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.