| name | quick-design |
| description | Lightweight design spec for small changes — copy tweaks, single-screen polish, parameter adjustments — when a full PRD is overkill. Produces a Quick Design Spec that embeds directly into a story file. Use when a change is too small to justify a new PRD section but still needs a written spec for traceability. |
| argument-hint | <change-name> [--story <story-path>] |
| user-invocable | true |
| allowed-tools | Read, Glob, Grep, Write, Edit, AskUserQuestion |
| model | sonnet |
Quick Design — Light Spec
For changes where opening /design-system would be heavyweight: copy tweaks, single-control re-designs, paywall-position changes, debounce tuning, error-message rewrites. The spec ends up embedded inside a story file, not as a standalone PRD.
Purpose / When to Run
Run when:
- A change is too small to update a full PRD section
- The PRD for the affected system is already complete and the change is a delta
- A bug fix has product implications worth recording
- The user types
/quick-design for a one-off tweak
Do not run when:
- The change crosses multiple systems → use
/design-system
- The change introduces a new system → use
/design-system
- The change has no PRD context at all → use
/design-system from scratch
Inputs
- Change name (required)
- Optional
--story <path> to embed the spec into a specific story
- Existing PRD for the affected system if any
design/concept.md
Outputs
Either:
- A standalone
design/quick/<change-name>.md, OR
- An appended
## Quick Design Spec block inside the named story file
Phase 1: Argument Resolution
If no change name is provided, ask:
- Prompt: "What is the change?"
- Free text — capture as kebab-case for filename.
Detect parent PRD: ask the user which existing PRD this change touches. Use Glob design/prd/*.md and offer the list as AskUserQuestion options if they don't know.
Detect mode:
--story <path> provided → embed mode- No flag → standalone mode (writes
design/quick/<change-name>.md)
Phase 2: Lightweight Context
Read only what is needed:
- The parent PRD section the change affects (not the whole PRD)
- The story file if embed mode
- Relevant entries in
design/design-bible.md if the change is visual
Print a one-line context summary: "Change touches PRD <system>, section <name>. Embedding into story <NNN>."
Phase 3: Capture the Spec
Use a compact Q&A loop. Each question maps to a section of the spec.
- What is changing? (one sentence)
- Why? — link to a bug, metric goal, user feedback, or concept-doc principle
- Specifically what is the new behavior? — exact copy / value / sequence / position
- What is replaced? — exact prior behavior, so the diff is unambiguous
- Who does this affect? — all users / new users only / paying users / specific cohort
- Are there edge cases? — minimum required: offline, accessibility, dark mode if visual
- How will we know it worked? — one or two acceptance criteria in GIVEN-WHEN-THEN
Use AskUserQuestion for cohort question (closed list); free text for the rest.
For visual / copy changes, also ask:
- "Copy: provide the exact final text" (free text)
- "Visual: any token changes from the design bible? Which?" (
AskUserQuestion with bible token names if bible exists)
For threshold / parameter changes, also ask:
- "Old value, new value, valid range, who can change it without a release?"
Phase 4: Draft the Spec
Build a compact block:
## Quick Design Spec — <Change Name>
> **Created**: <date>
> **Affects PRD**: `design/prd/<system>.md` § <section>
> **Cohort**: <all / new / paying / specific>
### Change
<one paragraph — what is changing and why>
### Behavior diff
**Before:** <exact prior behavior>
**After:** <exact new behavior>
### Edge cases
- <list, mobile-relevant>
### Acceptance criteria
- **GIVEN** <state> **WHEN** <action> **THEN** <observable result>
### Notes
- <any callouts — feature flag name, A/B test, kill switch, instrumentation event>
Keep this under 30 lines. If it grows past that, recommend converting to a full PRD update.
Phase 5: Approval & Write
Show the draft. Ask via AskUserQuestion:
- Prompt: "Approve and write this spec?"
- Options:
Approve — write to story (if embed mode)Approve — write to design/quick/<name>.md (if standalone)Make changes — describeDiscard
If embed mode: append the block to the story file using Edit, anchoring to the end of ## Acceptance Criteria or the bottom of the file.
If standalone: write the file with a header # Quick Design — <name> plus the block.
After write:
- Update the parent PRD's "Open Questions" section to note "see quick spec at " if a tracking link is useful
- Update
production/session-state/active.md
Phase 6: Suggest Next
Print:
"Quick spec written. If this change should ship in the active sprint, run /sprint-plan (or update the existing sprint plan)."
If embed mode: also note "Story <path> now has the embedded spec — run /story-readiness <path> before implementation."
Edge Cases
- The "small" change keeps growing: pause after question 3 if the change is touching more than one system or 3+ screens. Recommend
/design-system instead.
- No parent PRD: the change is too foundational for quick-design; redirect to
/design-system.
- The user wants the spec but not the story embed: write standalone. The story can reference the path later.
Quality Gates
- The spec must include at least one acceptance criterion in GIVEN-WHEN-THEN form
- The before/after diff must be exact — no "improve" language without the specific change
- For copy changes, the exact final string is captured verbatim
- For threshold changes, old value + new value + range are all specified
Examples
/quick-design empty-state-copy --story production/epics/onboarding/story-007-add-list.md
- Change: rewrite the empty state on the lists screen
- Before: "No lists yet."
- After: "Tap + to start your first list — it takes about 10 seconds."
- Acceptance: GIVEN a new account WHEN the user opens the lists screen THEN the new copy is shown.
- Embedded into the story file.
/quick-design paywall-trigger-timing
- Change: paywall now triggers after the 3rd successful action, not the 1st app launch
- Standalone spec written to
design/quick/paywall-trigger-timing.md
- Acceptance: GIVEN a free-tier user has completed 3 actions WHEN they attempt the 4th THEN the paywall is shown
- Notes: feature-flag
paywall_trigger_v2, A/B test against current behavior
