/plan

description: "Turn a design brief into a phased design plan: clarify gaps, classify complexity, decompose into lifecycle stages (Discover/Design), assign doctrine per phase, and set design done-when items (contrast ratios, token coverage, heuristic pass). Use after research, or standalone when the brief is already known."
argument-hint: "[research doc path or brief description]"

Command: plan

The plan is a contract between `plan` and `build`. It specifies WHAT to design and WHY at the strategic level, with explicit artifact seams between phases. It **references and sequences** doctrine by name — it never copies doctrine content.

This command obeys the shared contract in `docs/workflow-conventions.md` (the lifecycle, the artifact gates, the done-when vocabulary) and cites it rather than restating it.

---

Read the Input First

`$ARGUMENTS` is either a **research-doc path** or a **brief description**:

• **Path to an existing file** (e.g. `.design-foundations/research/2026-06-20-acme.md`): `Read` it. Its confirmed brief seeds the problem statement directly — you clarify only the gaps it left open, not the whole brief.
• **Path that does not exist:** say so ("No file at `<path>` — treating it as a brief description"), then use the text as the brief.
• **Plain text (not a path):** treat it as the brief and proceed.
• **Empty:** ask the user what they want to design.

A research doc carries confirmed intent. **Do not re-derive the brief from scratch** — read it, then fill only the gaps. A research doc's `## Taste signals` section, when present, carries dealer pins — copy them into the DNA phase's `**Constraints:**` verbatim rather than re-eliciting them.

---

Scan the Design State (sets the entry stage)

Before classifying, detect which design artifacts already exist. This decides where the plan *enters* the lifecycle — you do not re-plan work that is already done.

ls DESIGN.md JOURNEY.md 2>/dev/null

| Artifacts present | Entry stage | What the plan covers | |---|---|---| | Neither | **Discover** | Full lifecycle: Discover → Design | | JOURNEY.md only | **Design — DNA** | Skip Discover; plan the Design stages from DNA onward | | DESIGN.md locked (token block present + user-confirmed) | **Design — continue** | Skip Discover and DNA; plan the remaining Design stages (tokens, system, words, data) | | Both | **Design — compose** | Plan only the unfinished Design stages |

State the entry stage explicitly: "DESIGN.md is locked — resuming at the Design stage; Discover is already done." **Never redo a stage whose gating artifact already exists.** This is the mid-lifecycle resume contract (workflow-conventions.md §5).

---

Quick Classification

Read the brief and make an instant complexity call before any other work — the track determines everything downstream.

| Signal in the brief | Track | |---|---| | One surface, focused ask. "make this landing page feel premium." User knows the target even if not the execution. | **Quick** | | A product with several surfaces, multiple audiences, "how should this flow", needs a journey + a design system | **Standard** | | A redesign, a multi-surface product, a new brand from nothing, high uncertainty across both Discover and Design | **Full** |

**Default to Quick.** Under-planning a simple design is cheap to fix; over-planning a one-surface polish wastes the user's time. Only upgrade when the signals clearly demand it. A mid-lifecycle resume (DESIGN.md already locked) almost always shrinks the track — there is less left to plan.

---

Before Planning (all tracks)

These steps produce the confirmed problem statement that anchors all downstream phases.

1. Clarify gaps

Load `Skill(clarify)`. A research doc usually answers most of this — clarify **only its open questions**. Route each gap by shape: a genuinely decisive pick with self-contained 2-4 options (e.g., "which device class — phone, TV, or in-car?") → `AskUserQuestion`. An open-ended content gap (missing brand context, vague mood words, undefined audience, scope faults) → ask in conversation as end-turn markdown; the answer is prose the user has to elaborate, not a button they can tap, and a dialog can't hold it any better than the problem statement below can. Keep asking, in whichever channel fits each gap, until the answers are decisive and no new gaps remain.

**Cap: 5 rounds.** If still unclear at the cap, state your remaining assumptions explicitly and ask the user to object.

2. Problem statement

Write:

• **Problem:** 1-2 sentences — what we're designing and the job it does
• **Constraints:** non-negotiable boundaries (brand, device class, timeline, platform)
• **Success criteria:** how we know the design is done (in design terms — readable, on-brand, accessible, the journey works)

Render the statement as markdown in conversation and end the turn asking "Does this capture what you want to design?" — the user replies in their own words. Content confirmations happen in conversation, not in a dialog: the conversation is the only surface that renders the full statement (dialog previews truncate, and the user can't correct nuance through option buttons). Corrections → update and re-confirm. New gaps → re-enter clarify on those gaps. This becomes the plan's `## Context`. **No plan writing begins until the problem statement is confirmed.**

---

The lifecycle the phases decompose into

Every phase maps to one lifecycle stage. The stage fixes the doctrine and the gating artifact (workflow-conventions.md §1, §4).

| Stage | Concern | Doctrine | Gating artifact (Produces) | |-------|---------|----------|----------------------------| | **Discover — JTBD + IA** | how the user moves through time | `journey` | JOURNEY.md (Job + Journey + IA) | | **Discover — flows + page specs** | the route + page structure | `journey` | JOURNEY.md (Flows + Page specs) | | **Design — DNA + tokens** | the visual identity | `design-dna` (+ `archetypes`, `foundations`) | DESIGN.md