/plan-feature

Turn a PRD into a researched, reviewable Design Doc — the bridge from product hand-off to "R&D can start building". It does the deterministic mapping the PRD makes possible, then hands to the architect to do the real design work (code archaeology, the existing landscape, the actual API / schema / sequencing) and fill the doc completely. The output is meant to be read and approved by a reviewer, and built from by an implementation session — not refined from a stub.

What it produces

A Design Doc at docs/designs/<slug>-<cu-id>.md (Design Doc template, status: draft, related_prd → the PRD) that is:

• Concise and reviewer-first. It opens with a TL;DR a reviewer reads in a minute — the key design decisions and why, the design-system deltas, the risks / open calls. No restating the PRD, no filler.
• Complete enough to build from. Every section the implementer needs is filled by real research, not left "TBD" / "DRAFT — R&D refines": the existing landscape, API / contracts (§5), data model (§4), frontend & components (§6), observability (§7), and a §13 Task Breakdown with Effort (XS–XL), Risk, Depends on, and the design-system prerequisites listed first.

Plus a short summary (reused components, DS delta tasks by type, open questions raised + owners, the doc path).

Arguments

$ARGUMENTS — optional. A PRD path, a slug, or a free-language description ("the spotlight palette", "the command-palette PRD"). You never need to type a path: with no argument, the command lists the PRDs — read from origin/master, never your local branch — and lets you pick (step 1).

How it runs

1. Resolve which PRD against origin/master — never make the author type a path, and never trust the local branch. PRDs live on master (a promoted PRD is merged there); the local checkout is usually on an unrelated feature branch, so reading the working tree silently hides freshly-merged PRDs and can lock onto the wrong one. Always resolve from origin/master:

   • Fetch, then enumerate from the merged tree. Run git fetch origin master (quiet), then git ls-tree -r --name-only origin/master docs/prds/ (drop index.md); read each one's frontmatter with git show origin/master:<path> for its status / title / id.
   • No argument → list those PRDs, surfacing status: ready-for-rd ones first (the ready-to-plan set) and showing the rest with their status, then ask the author to pick one.
   • A slug or free-language description → fuzzy-match it against the origin/master PRD titles / slugs / ids. One clear match → confirm it in a line ("Spotlight (⌘K command palette) — that one?") and proceed on yes; several → list them to pick from; none → list all and ask. (A path to a real file is also accepted, but the canonical body is read from origin/master.)
   • Warn on a stale checkout. If git rev-list --count HEAD..origin/master is non-zero, note it in one line ("your checkout is N commits behind master — planning against the merged PRD") and continue; do not block, since resolution already uses origin/master.
   • Once resolved, read the PRD body from origin/master:<path> and require status: ready-for-rd — if it's still draft, say so and stop ("the PRD isn't hand-off ready — Gatekeeper hasn't approved it"). (An intake-promoted PRD is flipped to ready-for-rd by the hand-off / gatekeeper before this runs.)

2. Deterministic pre-pass — the scaffold the architect builds on:

   • Fetch the design reference. Figma Dev Mode via the Figma MCP if connected; a Claude Design code branch or a served HTML prototype otherwise; if unreachable, note the gap and use PRD §7.2.

   • Resolve §7.2 against the catalog (@bewith-dev/design-system COMPONENTS.md / src). Every component named in §7.2 must exist in the catalog or appear in §7.2.a. If one does neither, stop and send the PRD back to prd-writer — it names a component nobody is building.

   • Turn §7.2.a deltas into design-system tasks — one per non-reuse row, using the row's DS task command verbatim. Flag any delta-type ↔ command inconsistency rather than guessing (that's a prd-writer / gatekeeper miss). These tasks run in @bewith-dev/design-system and are prerequisites that ship before the feature is wired into the consuming app.

     Delta type	Design-system task
     reuse	none — reference the catalog import path
     variant	/add-variant <Component> <desc>
     element	/add-component <Name> element
     component	/add-component <Name> component
     composite	/add-composite <Name> <desc>

3. Hand to the architect for the real design pass. Invoke the architect on the PRD + the scaffold. The architect does what the deterministic pass cannot:

   • Code archaeology across the repos PRD §2 names — the existing model / service / controller patterns, persistence, transport, auth, and the current shape of what this feature touches. Design against the landscape as it actually is, never greenfield.
   • Pulls in the relevant specialists per its architectural-surfaces checklist — auth-security (mandatory on any permission / RBAC touch), contracts-schema (FE↔BE / inter-service contracts), database (schema / migration), design-system (the new components from §7.2.a), frontend-developer, observability, and others a surface fires.
   • Observability is mandatory when PRD §8.1 lists analytics events. Run observability for real, not as a footnote: for each §8.1 event, the payload schema, where it fires (FE / BE), the privacy constraints it must honour (e.g. a raw search query is never in the payload — only non-identifying metadata), and the metric / dashboard it maps to. A §8.1 with events that gets only "where it fires" is an incomplete §7 — do not let it pass as done.
   • Fills every section with concrete decisions: real endpoints + DTOs + error codes (§5), schema with indexes (§4), a sequence diagram for any flow crossing ≥2 services, rollback / feature-flag, and explicit backward-compatibility — then runs the Design Review Checklist.
   • Completes §13 Task Breakdown — the DS prerequisite tasks first (no upstream dependency), then the consuming-repo tasks, each with a conservative Effort (XS–XL), Risk, and the dependency edge that makes "design-system ships first" deterministic.
   • Flags candidate platform artifacts — proactively, the way a teammate would. If the design introduces a recurring operation the team will repeat by hand (e.g. registering a new entry into a code-defined registry, a repeated migration / backfill shape, a check that should run every time), name it as a candidate /new-artifact — a skill, command, or hook — and say what it would automate. Record it as a §13 task or a §15 open question. Propose; never build it here.

4. Iterate with the human on genuine open questions — do not fill with assumptions. When research surfaces a decision only the author / R&D can make (or that needs a colleague), stop and ask it, concisely, one at a time (the architect's rule: designing against an unclear ask is the most expensive mistake). Resolve what archaeology can answer; escalate what it cannot. Record resolutions in the doc; leave non-blocking ones in its open-questions section with an owner. Never bury a decision silently.

5. Write the Design Doc to docs/designs/<slug>-<cu-id>.md on a fresh branch off origin/master (e.g. docs/<slug>-design), not whatever branch the checkout happens to sit on — the symmetric trap to reading the PRD off a stale branch. Template shape, status: draft, related_prd → the input; lead with the TL;DR. In §6, a reuse component maps to its catalog import; a non-reuse one references its §7.2.a design-system task as a prerequisite.

6. Summarize to the developer. Reused components count; DS delta tasks by type (all flagged prerequisites); any §7.2 ↔ §7.2.a inconsistency (and that it was sent back to prd-writer); any candidate platform artifacts proposed (filed as §13 tasks / §15 questions, not built); the open questions raised + their owners; the path to the Design Doc.

What this skill does NOT do

• It does NOT write feature code — only the Design Doc.
• It does NOT create the GitHub Issues — that's /breakdown, after the Task Breakdown is reviewed.
• It does NOT create the ClickUp parent task — that comes from the PRD hand-off, before this runs.
• It does NOT approve the Design Doc — human R&D + gatekeeper (Mode B) move it past draft.

Cross-references

• architect — the design authority this command drives; the codebase research and the Design Doc authorship live there.
• Product ↔ R&D Handoff methodology — the pipeline this command sits in.
• PRD template — the input shape; §7.2.a is the design-system delta list this command parses.
• Design Doc template — the output shape (TL;DR + §13 Task Breakdown with effort).
• @bewith-dev/design-system — the SoT the deltas anchor to; the /add-variant, /add-component, /add-composite commands live there.
• /breakdown — the next step (after the Task Breakdown is reviewed).