design-sprint

name	design-sprint
description	Design this, create a spec, design sprint, architecture for this, write a design doc. Post-ideation: architecture, components, data flow, error handling, testing. Not for ideation — use brainstorm-session for that.

Software Design Sprint

Turn a chosen software approach into a complete, reviewable design spec ready for implementation planning.

Prerequisite: The user has already decided WHAT to build (either through brainstorm-session or by coming in with a clear idea). This skill handles HOW to design it.

Do NOT write any code, scaffold any project, or invoke any implementation tool until the design is approved by the user. This is a DESIGN skill, not an implementation skill.

Required reading: Read references/facilitation-principles.md before facilitating. It defines the questioning discipline (one at a time, multiple-choice preferred), the engagement signals, and the anti-anchoring depth this skill depends on.

Execution: parallel-first

• Step 1 context exploration — file reads, recent commits, and related spec discovery have no inter-step dependencies. Batch them.
• Step 4 isolation design — if the design references multiple existing components or specs, Read them in parallel.
• Step 7 spec review — any file reads within the review are parallel.
• Always serialize: the per-section approval loop in Step 5 (user must respond before the next section).

Checklist

Complete these steps in order:

1. Explore project context — Check files, docs, recent commits (including docs/design.md if present — that file is the project's brand / UI/UX design direction; honor it as a constraint, never write to it)
2. Confirm scope — Verify the chosen approach with the user. If they haven't chosen, route them back to brainstorm-session.
3. Ask clarifying questions — One at a time, focused on technical design decisions
4. Design for isolation — Break into units with clear boundaries and interfaces
5. Present design sections — One section at a time, get approval after each:
   • Architecture overview
   • Component breakdown
   • Data model / flow
   • API design (if applicable)
   • Error handling strategy
   • Testing strategy
   • Migration / deployment considerations (if applicable)
6. Write design doc — Deliver as one self-contained file; ask where (see "Delivering the spec" below)
7. Spec review — Inline self-review checklist, then at most one spec-reviewer dispatch (see "Spec Review" below)
8. User reviews spec — "Spec written to <path>. Please review and let me know about any changes."
9. Transition — Hand off to /rad-planner:plan for implementation planning (see "After the Design" below)

Design Principles

Design for Isolation and Clarity

• Break the system into smaller units that each have one clear purpose
• Units communicate through well-defined interfaces
• Each unit can be understood and tested independently
• Ask for each unit: what does it do, how do you use it, what does it depend on?
• Can someone understand what a unit does without reading its internals?
• Can you change internals without breaking consumers?
• When a file grows large, that's a signal it's doing too much

Follow Existing Patterns

• Explore the current codebase structure before proposing changes
• Follow existing conventions (naming, file organization, testing patterns)
• Where existing code has problems that affect the work, include targeted improvements
• Don't propose unrelated refactoring

YAGNI

• Remove unnecessary features from all designs
• Don't add configurability that hasn't been requested
• Don't design for hypothetical future requirements
• The right amount of complexity is the minimum needed for the current task

Asking Questions

• One question per message
• Prefer multiple choice when the options are known
• Focus on decisions that affect the design (not implementation details)
• If a topic needs more exploration, break it into multiple questions

Presenting 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
• Be ready to go back and revise if something doesn't make sense

After the Design

Delivering the spec

One self-contained markdown file — ask the user where, with two sensible options:

• Into the project (the usual choice): a dated doc under docs/ (suggest docs/YYYY-MM-DD-<topic>-spec.md), with a header marking it transient: "Design spec — consumed by /rad-planner:plan; archive after planning." The repo's doc-hygiene tooling (rad-repo-manager) will later flag it for archiving — that's the designed lifecycle. Never write to docs/design.md: that file is the project's brand / UI/UX design direction, not a technical spec.
• Personal folder (pre-repo projects): suggest ~/Documents/Brainstorms/YYYY-MM-DD-<topic>-spec.md; on Claude Desktop / Cowork, also surface the file so it can be saved or downloaded directly.

Use clear, concise language. Never auto-commit — the user commits via their normal flow.

Spec content rules

• "Considered and rejected" section — every spec includes one: the design alternatives that were ruled out, each with a one-line why. The implementing agent should see what was ruled out and why.
• Rejected + parked ideas → docs/ideas.md — when the host repo has a docs/ideas.md, also append rejected and parked alternatives there, each with its one-line "why." Anti-re-proposing. No docs/ideas.md? The spec's section carries them.
• No placeholders — "TBD," "add appropriate error handling," "similar to X" are named failures. Every requirement is concrete or explicitly deferred with a reason.
• Vocabulary quarantine — inside a repo, the spec never uses Release/Milestone/Task terms and never emits plan-shaped artifacts; all sequencing belongs to /rad-planner:plan.

Spec Review

1. Inline self-review first (free, always). Before any agent dispatch, check the spec yourself:

• Placeholder scan — any "TBD", "TODO", "add appropriate...", "similar to X"?
• Internal-contradiction check — does any section conflict with another?
• Scope check — does anything exceed what was agreed in Step 2?
• Ambiguity check — could any requirement be read two ways? Pick one and state it.

Fix what the self-review finds.

2. At most one spec-reviewer dispatch. Then dispatch the spec-reviewer agent once with the substituted references/subagent-prompts/spec-review.md template. Parse the JSON response:

• status: approved → proceed to user review gate
• status: issues_found → fix the blocking issues, then surface the review to the user: "Spec review found these issues; I've addressed them. Want another review round, or shall we proceed to your review?" Further reviewer rounds only if the user asks.

Markdown fallback is accepted from the agent — parse best-effort if JSON is missing.

User Review Gate

"Spec written to <path>. Please review it and let me know if you want to make any changes before we start the implementation plan."

Wait for user response. If changes requested, make them and re-run the inline self-review (a fresh reviewer dispatch only if the user asks).

Transition

Hand off to /rad-planner:plan to turn the approved spec into a release-map implementation plan with risk review — rad-planner v7+ pre-fills its discovery interview from this spec, so the user won't be re-asked what the spec already answers. If rad-planner is not installed, surface this to the user and suggest installing it, or let the user invoke their preferred implementation-planning workflow.

Do NOT invoke frontend-design, mcp-builder, or any other implementation skill directly from design-sprint — implementation planning is a separate, reviewable phase.