update-prd

Update the Product Requirements Document: $ARGUMENTS

Core references. A citation of the form workflows-core:<name> names a shared reference in the workflows-core plugin. Load it with Skill(skill: "workflows-core:reference", args: "<name>") — never by path: ${CLAUDE_PLUGIN_ROOT} resolves to this plugin, which does not carry it.

/update-prd refreshes an existing Product Requirements Document (PM phase). It covers routine refreshes (new information, scope tweaks, wording) and the rare obstacle-driven re-do (a human read an ARD/spec finding, discussed it, and decided the PRD must change). The PRD is product-level — what / why / for-whom, not how. Zero code scan; no repos.

Usage: /update-prd <KEY> [@transcript-or-notes ...] [--no-docs] [--docs <path>] (--no-docs turns off documentation grounding for the run — see Phase 1). --docs <path> — points documentation grounding at that root for this run instead of ${DOCS_PATH:-/workspace/docs}; strip the flag and its value together before any remaining-argument classification, or the path is read as part of the address. Declared for every consumer by workflows-core:docs-grounding Procedure step 1 (Flags first), which resolves it; this command only has to recognise it and pass the invocation through.

Phase 0 — Resolve inputs

1. Flags. Strip --no-docs (boolean) and --docs <path> — the flag and its value together — from $ARGUMENTS before anything else reads it. Both are carried to Phase 1's resolve-docs-grounding call and change nothing else. This step is load-bearing rather than tidy: Phase 0 step 5 consumes "any @transcript / notes path(s) passed in $ARGUMENTS", so an unstripped --docs value is read in as a grounding source and its content reaches the PRD.
2. KEY (mandatory). Parse the first token that is neither a flag nor a flag's value — --docs consumes the token after it (step 0), and a value skipped as "non-flag" would be read as the key and validate it with key-valid (workflows-core:addressing §1) — the grammar is that file's, cited rather than copied here. If absent or malformed, stop: UPDATE_PRD_NEEDS_KEY: /update-prd needs the PRD's key — '/product-workflows:update-prd <KEY>'. The grammar is a superset of the two-segment form — every key that validated before still validates, so a PRODUCT-1234 refresh behaves exactly as it did — and it is the one this command needs for the same reason step 3's folder resolution is: a PRD authored inside a BRD slice by /create-prd on the BRD route carries a three-segment key (EPIC-008-01), and /create-prd redirects here on finding it. A validation narrower than /create-prd's would refuse that redirect at the door, which is the identical dead-end step 3 exists to close, one step earlier.
3. $SPECS_PATH (required). If unset, stop naming SPECS_PATH (choices: ["Set SPECS_PATH (enter the path)", "Cancel"]).
4. Feature folder. Resolve it with resolve-address <KEY> (Skill(skill: "workflows-core:reference", args: "addressing resolve-address"), §3), which searches every level §3 bounds and carries §5's legacy fallback; ambiguous → stop, naming every match and @<path> as the way through. status: absent is a stop, not a folder to create: surface the key dir not found rule in Skill(skill: "workflows-core:reference", args: "escalation-rules") (choices: ["Re-enter key", "Cancel"]) and name /product-workflows:create-prd <ADDRESS> as the run that authors a PRD where none exists. Named unqualified here and only conditionally at step 4, and the difference is what resolved: nothing did. There is no folder, so there is no brd-link.md, no gate set and no kind to test — ${CLAUDE_PLUGIN_ROOT}/references/coverage-ledger-format.md §5.2's Only a BRD-route folder has a gate set at all is the case that applies, and the container refusal that is /create-prd's third has no folder to fire on. Step 4 reports a folder that does exist, which is why it tests all three before it names that command. No matching rule is written here — §5 owns it. 3a. An Epic folder is refused before step 4 reads it. resolve-address searches every level §3 bounds, the Epic level included, so an Epic's key resolves here exactly as a PRD's does — and an Epic folder is never where a PRD lives: its PRD is the one in the folder above it. Without this step an EPIC- folder reaches step 4, which finds no prd.md and, carrying no brd-link.md, takes the idea-route row and names /product-workflows:create-prd <ADDRESS> — a run that refuses the same folder with CREATE_PRD_EPIC_FOLDER; and a prd.md that an earlier /create-prd wrote into an Epic folder, before that refusal existed, would be refreshed in place as though it were a PRD. Take the test the moment step 3 returns status: found, on the folder, never on the kind a carrier asserts: an EPIC- prefix as workflows-core:addressing §4.1 defines one (the name beginning EPIC-<the resolved key>-, so a legacy folder keyed EPIC-008-01 is not refused by its name), or, on a folder with no prefix, §4.1's positive evidence — a resolved kind: epic, taken after §5.1's container test as §4.1 orders it. Stop gracefully:

   UPDATE_PRD_EPIC_FOLDER: <KEY> resolves to an Epic folder at <path>, and an Epic is never the folder a PRD lives in — a PRD lives in a PRD- folder, and this Epic's PRD is the one in the folder above it. <remedy>
   

   <remedy> names the parent PRD as the likely intended target wherever there is one: where the folder above holds a prd.md asserting kind: prd, This is probably the PRD you meant: re-run '/product-workflows:update-prd <PRD-KEY>'; to re-refine this Epic instead, run '/product-workflows:epics <KEY>'., <PRD-KEY> being that prd.md's own key (workflows-core:addressing §4), never parsed out of either folder's name — and where this folder holds no epic.md, /product-workflows:epics <KEY> refuses it (EPICS_NO_PRD), so that clause names '/product-workflows:epics <PRD-KEY>' instead; where the folder above holds none, this Epic has no PRD above it, the shape /product-workflows:epics <KEY> reports as EPICS_EPIC_NOT_UNDER_PRD where this folder holds an epic.md and as EPICS_NO_PRD where it holds none, and the remedy is the one both stops give: where the folder above is a PRD- folder, The PRD folder above it holds no PRD yet: author one there with '/product-workflows:create-prd <PARENT-KEY>'., <PARENT-KEY> being that folder's own key, subject to step 4's table applied to that folder where it carries a brd-link.md; anywhere else, name no parent and say so. It is a user halt, so emit-block does not fire.
5. Resolve the base PRD. It is the prd.md in the folder step 3 resolved — the only current copy there is (earlier revisions are archived under revisions/ and never read as the base), and therefore authoritative without a test. Absent → stop gracefully:

   UPDATE_PRD_NO_PRD: <ADDRESS> resolves a folder at <path> holding no prd.md, and /update-prd refreshes an existing PRD rather than authoring one. <the remedy, per the row below that matches>