| name | prd-docs |
| description | Use when authoring a new PRD or upgrading a lean PRD to standard. Walks user through 20-section problem-first scaffold (or 10-section lean), pre-populates from prior /research transcript if present, defers Terminologies (§2) until after the rest is drafted (auto-fills from research glossary + scan of body), invokes shield:story-coverage between Sections 6 and 8 and shield:milestone-coverage between Sections 8 and 15, prompts for story Type (new/enhancement/existing), supports custom team templates via .shield.json. Triggers on /prd, write a PRD, author a PRD. |
PRD Docs
Author a new PRD with the Shield 20-section problem-first scaffold (or 10-section lean variant), or upgrade an existing lean PRD to standard by adding missing sections.
Output Path — MANDATORY
{output_dir}/{feature}/
├── prd.md ← registry: {prd} = {feature_dir}/prd.md
├── outputs/prd.html ← registry: {prd_html} = {feature_outputs}/prd.html
└── prd.meta.json ← side-artifact (metadata sidecar, not in registry)
Where {output_dir} comes from .shield.json and {feature} is the feature folder. Numbered run subfolders (prd/{N}-{slug}/) are gone — prd.md lives flat in the feature folder.
prd.meta.json is metadata (records type, status, owner, last_updated, rubric_version, and linked_plans auto-populated by /plan) — it is a side-artifact like the manifest, not a primary deliverable, so it is not in the outputs: registry.
When to Use
- User invokes
/prd to author a new PRD
- User invokes
/prd in a feature folder containing a lean PRD (triggers upgrade flow)
When NOT to Use
- Review an existing PRD — use
/prd-review instead
- Generate a plan from a PRD — use
/plan instead
- Capture pre-PRD context — use
/research instead
Step Skeleton
| Step | Action | Condition | Mandatory |
|---|
| 1 | Read .shield.json for prd_template, prd_required_sections | always | Yes |
| 2 | Resolve feature folder context | always | Yes |
| 3 | Check for prior PRD in feature folder (lean → trigger upgrade flow) | only if prior PRD exists | conditional |
| 4 | Ask user for PRD type (standard | lean) | always |
| 5 | Check for prior /research transcript; pre-populate Problem/Personas/Dependencies if present; note glossary rows for §2 Terminologies (step 13) | only if research exists | conditional |
| 6 | Walk Section 1 (Header) | always | Yes |
| 6a | Insert empty Terminologies placeholder for §2; fill later (step 13) | always | Yes |
| 7 | Walk Sections 3, 4 (Problem, Personas) | always | Yes |
| 7a | Walk Section 5 (Architecture & flows) — optional; user adds Mermaid blocks / image links, or leaves empty | always | Yes |
| 8 | Walk Section 6 (Goals) | always | Yes |
| 9 | Invoke shield:story-coverage between Sections 6 and 8 — scaffold expected stories | standard only | conditional |
| 10 | Walk Section 7 (Metrics) and Section 8 (Stories with Type prompt) | always (lean: only §7) | Yes |
| 11 | Invoke shield:milestone-coverage between Sections 8 and 15 (standard) or after Section 7 (lean) | always | Yes |
| 12 | Walk Section 15 rollout-mechanics; Sections 16..20 (standard) or §9, §10 (lean) | standard only for §15-§20 | conditional |
| 13 | Build Terminologies (§2) — research-glossary copy + LLM scan of drafted body, user confirms | always | Yes |
| 14 | Apply custom-template merging if .shield.json.prd_template is set | only if config set | conditional |
| 14b | Apply shield:writing-style to all author-written prose (NOT rendered/marker-wrapped sections or the §2 Terminologies table values) before writing | always | Yes |
| 15 | Write prd.md, prd.html, prd.meta.json | always | Yes |
| 16 | Update manifest, regenerate index.html | always | Yes |
Workflow
1. Configuration
Read .shield.json:
output_dir (default docs/shield)prd_template (default null — use built-in scaffold from templates.md)prd_required_sections (default: ["Problem", "Goals & non-goals", "Success metrics", "Out of scope", "Open questions"] — see spec)
2. Feature context
Determine which feature folder this PRD belongs to:
- If
--feature <name> flag passed → use that
- Else look at current working directory hint (recent activity) and ask user to confirm
- If no prior feature folders exist → create one with today's date
3. Detect prior lean PRD (upgrade flow)
Read {output_dir}/{feature}/prd.meta.json. If it exists and has type: "lean":
Offer the user a multi-select:
I found a lean PRD in this feature folder. What would you like to do?
[ ] Add sections (a new run is created with your existing content + new sections)
Note: lean §2 Terminologies and §5 Architecture & flows carry forward unchanged.
Note: lean §8 Milestones content migrates into standard §15's Milestones
sub-table — the standard scaffold doesn't have a standalone §8 Milestones
(§8 in standard is User stories).
[x] Section 8 — User stories & scenarios
[x] Section 9 — Functional requirements
[x] Section 10 — Non-functional requirements
[x] Section 11 — RBAC & permissions matrix
[x] Section 12 — Dependencies
[x] Section 13 — Risks & mitigations
[x] Section 14 — Assumptions
[x] Section 15 — Rollout plan (mechanics; milestones already in lean §8)
[x] Section 16 — Cost & resource impact
[x] Section 17 — GTM & customer-comms
[x] Section 18 — Support / CX impact
( ) Start fresh — new run, blank slate
( ) Cancel
If user picks "Add sections":
- Read the existing
{output_dir}/{feature}/prd.md and {output_dir}/{feature}/prd.meta.json (flat paths — no numbered subfolder)
- Copy existing lean content forward into the upgraded PRD
- Walk the user through the chosen new sections only
If "Start fresh" or no prior lean PRD detected, proceed to Step 4.
4. PRD type prompt
Which PRD type would you like?
1. Standard — full 20-section scaffold (recommended for substantial features)
2. Lean — 10-section variant (good for 1-pagers, small features, "stop me if this is wrong" docs)
Record user choice. Type is per-invocation; not stored in .shield.json.
5. Pre-populate from prior research
Look for {output_dir}/{feature}/.session-transcript.md (falls back to {output_dir}/{feature}/research.md if the transcript is absent). If found:
- Read it
- Extract Problem context, Target Users (personas), Constraints (Existing systems / compliance markers)
- Pre-populate the corresponding sections in the PRD draft
- Also note any
## Glossary, ## Terminology, or ## Terms section — these rows will all be copied verbatim into §2 Terminologies at step 13
- Tell user: "I pre-populated Sections 3 (Problem), 4 (Personas), 12 (Dependencies) from your research transcript. Confirm or edit before we continue."
6. Walk Section 1 and defer Section 2
Walk Section 1 (Header) — present the template fields and ask the user for content. Then insert an empty Terminologies table as a placeholder for Section 2; do NOT walk it now. It is filled in step 13 once the rest of the PRD has content to scan.
7. Walk Sections 3, 4, then 5, then 6
Walk Section 3 (Problem) and Section 4 (Personas) — skip pre-populated fields unless the user wants to edit.
Then walk Section 5 (Architecture & flows).
Before drafting §5, run the architecture elicitation Q&A from
shield/skills/general/architecture-authoring.md at the Context level
(actors, external systems, primary flows). Auto-fill any answers already
present in the research transcript or earlier PRD sections and confirm them
rather than re-asking. Record anything the user is unsure about in §19 Open
Questions — do not invent structure.
Diagrams are Mermaid (conventions live in the standard). Sanity-check syntax
by trying a quick parse if the user pastes Mermaid; the renderer will surface
errors — don't block on syntax.
When emitting Mermaid diagrams, follow shield/skills/general/mermaid-authoring.md
(hard syntax rules — no semicolons, no reserved-word actors, balanced blocks).
Then walk Section 6 (Goals).
8. Story coverage scaffolding (standard only)
Once Sections 4 (Personas) and 6 (Goals) are captured, invoke shield:story-coverage skill with:
personas: from Section 4goals: from Section 6feature_domain: inferred (see story-coverage SKILL.md "Domain detection")
The skill returns expected_stories[]. Present them to the user with multi-select:
For coverage of your personas and goals, you'll likely want these stories:
[x] P1-S1 — Anika resets her password (persona-goal: P1 + G1, severity P0)
[x] P1-S2 — Anika handles login lockout (archetype: account-recovery, severity P1)
[x] P2-S1 — Rohan changes his email (archetype: email-change, severity P2)
Pick which to scaffold (defaults to all suggested), or add your own.
Selected stories are seeded into Section 8 with the standard story template structure (blank for the user to fill). Each scaffolded story is created with Type: new as the default placeholder — the user will override during the walk in step 10.
9. Story Type prompt protocol
For each story (scaffolded by step 8 or added by the user), walk the template fields. For the Type field, prompt:
Story <ID>: <name> — what's the Type?
1. new — behavior does not exist today (default)
2. enhancement — modifies existing user-visible behavior
3. existing — already exists; documenting for context (regression surface)
If the user picks enhancement or existing, also prompt:
Briefly name the existing behavior (path, link, or one-line description):
Substitute both fields into the story template before walking the remaining fields.
This protocol is applied during ### 10's §8 walk, not at this heading.
10. Walk Sections 7 and 8
Walk Section 7 (Success metrics), then Section 8 (User stories — scaffolded by step 8; apply the Type prompt protocol from step 9 to each story as you walk it).
11. Milestone scaffolding (both scaffolds)
After Section 8 (standard, once stories are filled) or after Section 7 (lean, once metrics are filled), invoke shield:milestone-coverage with:
personas: from Section 4goals: from Section 6stories: from Section 8 (standard only — pass empty for lean)feature_domain: same inference as story-coveragesuccess_metrics: from Section 7 (optional)
The skill returns milestones[] plus open_conflicts[]. Present them to the user:
Milestone proposal — refine before approving:
[x] M1 — Login core (PM + agile-coach agreed)
Outcome: Users can log in with email + password
Exit: Login endpoint returns 200 + session token...
Depends on: —
[x] M2 — Password recovery (PM + agile-coach disagreed on depends_on — see below)
Outcome: Users can reset a forgotten password without contacting support
Exit: Recovery email delivered within 60s; reset link single-use, 15-min TTL
Depends on: M1
⚠ Conflict: PM proposed `depends_on: []`. Agile-coach proposed `depends_on: [M1]`.
Agile-coach reason: "Recovery needs the session middleware shipped in M1."
Decision needed: keep [M1] / clear / edit.
Pick which to keep (defaults to all suggested), edit fields per row, or add your own.
Selected and edited milestones are written into:
- Standard: §15 Milestones table (then walk §15 rollout-mechanics fields next as in the standard flow).
- Lean: §8 Milestones table (then proceed to §9 Open questions).
If the user declines (empty selection), leave the Milestones table empty. /plan will re-run shield:milestone-coverage as a fallback if needed.
12. Walk Sections 9-20
Walk Sections 9-14 in order. Section 15's Milestones table is pre-populated by step 11 — walk only the Rollout-mechanics fields beneath it. Then walk Sections 16-20.
For lean PRDs, walk lean §9 (Open questions), then §10 (Out of scope). Do NOT walk standard §8-§18; lean omits them intentionally. Use the lean scaffold from templates.md, not the standard one.
13. Build Terminologies (§2)
Now that Sections 3-20 have content (or 3-10 for lean), populate the Terminologies placeholder inserted in step 6a.
Source A — research transcript glossary (REQUIRED copy, zero filtering). If a /research transcript exists at {output_dir}/{feature}/.session-transcript.md (falls back to {output_dir}/{feature}/research.md), scan it for any ## Glossary, ## Terminology, or ## Terms section. Parse rows (table or bullet list). Copy EVERY row verbatim into the Terminologies table.
Rules for Source A copy:
- Include ALL rows — including business/marketing/product terms (e.g., "ICP", "PLG", "GTM", "CAC") that may seem unrelated to the feature's technical domain. These terms appear in the research for a reason and reviewers depend on them.
- Preserve the exact term name and definition from the transcript row. Do not rephrase.
- Do NOT skip a row because it seems obvious, irrelevant, or non-technical.
- Do NOT drop a row because you have a better definition for the same concept.
If the research transcript has 2 rows (e.g., ICP + PLG), the Terminologies table MUST have both of those rows plus any Source B additions. A Terminologies table with only 1 of the 2 glossary rows is an error.
Source B — LLM scan of drafted PRD body. Scan Sections 3..20 (or 3..10 for lean) and propose 5–15 additional terms that meet at least one of:
- ALL-CAPS acronyms used 2+ times (e.g., "SLA", "RBAC")
- Capitalized multi-word phrases used as named concepts (e.g., "Sign-off Contact", "Kill-switch")
- Domain nouns in Personas, NFRs, or Dependencies without prior definition
- Internal product / service names referenced in Dependencies / GTM / Rollout
For each term, propose a one-line definition that prefers terminology from the PRD's own prose. Reference the research-transcript source path when applicable.
Grounding guard — MANDATORY. Source B additions MUST be grounded in body text the SKILL wrote in Sections 3..20 before this step. Do NOT add canonical or "obviously relevant" auth / cloud / domain terms (e.g., JWS, OAuth, TLS, p99, SLO) that you happen to know but never used in the prose. A row's only occurrence cannot be the Terminologies row itself.
Concrete check before substituting the table: for every Source B candidate row, count occurrences of the term in the PRD body excluding the Terminologies section. If the count is 0, DROP the row — even if the term is canonical for the domain. The "used 2+ times" criterion is measured in the body, not anticipated. If you find yourself wanting to keep an ungrounded but canonical term, edit the body to actually use it first, then re-scan.
Merge. Deduplicate by lowercased term. Source A rows win on conflict.
User confirmation. Present the merged table. Offer: accept all, edit, add, remove rows. Default: accept all.
Substitute the final table into Section 2.
14. Custom-template merging
If .shield.json.prd_template is set:
15. Write artifacts
- Write
{output_dir}/{feature}/prd.md (registry key: prd)
- Pre-flight: ensure
uv is available. Run command -v uv first. If missing, do NOT call the renderer yet — first prompt the user:
prd.html rendering requires uv (one-time install, ~/.local/bin).
Install now? (y/n)
[y] Run: curl -LsSf https://astral.sh/uv/install.sh | sh
[n] Skip — prd.md is written, prd.html will be missing until you re-run /prd after installing uv
If user agrees, run the installer via Bash, then export PATH="$HOME/.local/bin:$PATH" in the same shell so the next step finds it. If user declines, write prd.md and prd.meta.json but skip prd.html and surface the warning in the step-16 summary.
- Render
{output_dir}/{feature}/outputs/prd.html (registry key: prd_html) via the helper using the shared shell at $CLAUDE_PLUGIN_ROOT/templates/shell.html:
- Ensure the
{output_dir}/{feature}/outputs/ directory exists before writing.
- From the feature dir, run:
"$CLAUDE_PLUGIN_ROOT/scripts/render-markdown.sh" \
--md prd.md \
--shell "$CLAUDE_PLUGIN_ROOT/templates/shell.html" \
--out outputs/prd.html \
--assets-root "{output_dir}" \
--title "PRD — {feature}"
- Refresh the manifest-derived page assets (manifest.js + static asset bundle):
uv run "$CLAUDE_PLUGIN_ROOT/scripts/write_shield_assets.py" --output-dir "{output_dir}"
Do NOT write per-skill *.shell.html files — the shared shell at $CLAUDE_PLUGIN_ROOT/templates/shell.html owns DOCTYPE/head/nav/footer. Do NOT hand-render prd.html or pipe through pandoc/python-markdown — those mis-handle nested lists, lists-after-paragraphs, mermaid fence rules, and loose/tight wrapping.
- Write
{output_dir}/{feature}/prd.meta.json (per meta-schema.md) — side-artifact metadata sidecar, not a primary deliverable
16. Update dashboard
- Append new entry to
{output_dir}/manifest.json
- Regenerate
{output_dir}/index.html
17. Offer next steps
PRD authored. What's next?
- /prd-review — review for gaps (reads prd.md from the feature folder)
- /plan — generate a technical plan from this PRD
Common Mistakes
| Mistake | Fix |
|---|
| Writing prd.md without prd.meta.json | Both are mandatory; meta.json holds the type + linked_plans for downstream commands |
| Skipping story-coverage scaffolding for standard PRDs | Required step for standard; skipping leads to poor dim 4 grades downstream |
| Walking lean PRD through all 20 sections | Lean is intentionally 10 sections (its own numbering); use the lean scaffold from templates.md, not the standard one |
| Forgetting custom-template required-section merging | Custom templates MUST have all required sections; Shield appends missing ones with markers |
| Walking §2 (Terminologies) in order during the first pass | §2 is intentionally deferred; placeholder inserted in step 6a, content filled in step 13 after the rest of the PRD is drafted |
| Treating §5 as optional or skipping the C4 Context walk | §5 is the C4 System Context level — required. Run the elicitation Q&A from shield/skills/general/architecture-authoring.md; route genuine unknowns to §19 Open Questions; never fabricate. |
| Dropping Source A research-glossary terms from Terminologies | ALL terms from the research transcript's glossary section MUST appear in the Terminologies table — do not filter by domain relevance |
| Adding ungrounded canonical terms to §2 Terminologies (e.g. JWS, OAuth, TLS, SLO when never used in body) | Source B is a scan of the body, not a domain-vocab dump. Before substituting the merged table, recount each candidate term's occurrences excluding the Terminologies section — if 0, drop the row. The "used 2+ times" criterion is measured in the body, not in your prior knowledge. |
| Forgetting the Type field on stories | Every story in §8 MUST have Type (new/enhancement/existing). For rewrites, "existing" stories make regression surface visible |
| Mirroring §8 story AC as G/W/T FRs in §9 | §9 should only contain rules §8 doesn't capture (cross-story invariants, architectural commitments, negative "shall not" requirements, background/operational behaviors, data-handling rules, inter-service contracts). If an FR has a 1:1 back-pointer to a single story and says nothing the story doesn't, drop it. |
| Auto-detecting type without confirming with user | Type detection is best-effort; ALWAYS confirm with user |
| Writing to a path other than {output_dir}/{feature}/ (e.g. creating a numbered prd/{N}-{slug}/ subfolder) | prd.md must be written flat in the feature folder: {output_dir}/{feature}/prd.md |
Writing a per-skill prd.shell.html | The HTML shell is centralized at $CLAUDE_PLUGIN_ROOT/templates/shell.html — point --shell at it. Do not write or delete per-skill shell files. |
| Hand-rendering prd.html without render-markdown.sh | Always use render-markdown.sh; other renderers don't apply the mermaid fence rule or anchors plugin |
Skipping write_shield_assets.py after rendering | Every render pass MUST end with uv run "$CLAUDE_PLUGIN_ROOT/scripts/write_shield_assets.py" --output-dir "{output_dir}" so manifest.js + static assets stay in sync with manifest.json |
| Dropping or duplicating lean §8 Milestones during upgrade to standard | The lean §8 Milestones table MUST migrate into standard §15's Milestones sub-table. Do NOT keep it as standalone §8 (that's Stories in standard) and do NOT duplicate it. The upgrade flow's Note line explicitly calls this out — agents that miss it produce corrupted PRDs. |
See Also
templates.md — 20-section scaffold + 10-section lean variant + HTML render templatesmeta-schema.md — prd.meta.json schematype-detection.md — lean vs standard heuristicsshield:story-coverage skill — invoked between Sections 6 and 8 for scaffoldingshield:milestone-coverage skill — invoked between Sections 8 and 15 (standard) or after Section 7 (lean) for milestone scaffolding
