| name | prd-review |
| description | Use when a PRD exists (file, paste, URL) and needs gap analysis. Dispatches PM, agile-coach, tech-lead, DX, cost reviewer agents in parallel against a 13-dimension rubric; produces scored summary with severity-tiered gaps and P0-gated verdict. Triggers on /prd-review, review my PRD, PRD gap analysis. |
PRD Review
Dispatch parallel expert reviewer agents against a PRD to produce a scored analysis with prioritized gaps, severity tiers, and an enhanced PRD with suggested fixes.
Output Path — MANDATORY
All review output goes into a per-run, date-keyed folder under the feature's reviews/prd/ directory:
{output_dir}/{feature}/reviews/prd/{date}{_counter}/ ← {review_dir}
├── summary.md ← {review_summary} (main output)
├── source-prd.md ← verbatim source snapshot (side-artifact)
├── enhanced-prd.md ← {review_enhanced} (P0/P1 inline + P2 comments)
├── review-comments.json ← canonical structured per-section gaps (side-artifact)
└── detailed/
├── pm-reviewer.md ← {review_detailed} (agent=pm-reviewer)
├── agile-coach.md ← {review_detailed} (agent=agile-coach)
├── tech-lead-reviewer.md ← {review_detailed} (agent=tech-lead-reviewer)
├── dx-reviewer.md ← {review_detailed} (agent=dx-reviewer)
└── finops-analyst.md ← {review_detailed} (agent=finops-analyst)
{output_dir}/{feature}/outputs/reviews/prd/{date}{_counter}/ ← {review_outputs_dir}
├── summary.html ← {review_summary_html}
└── enhanced-prd.html ← {review_enhanced_html}
Where {output_dir} comes from .shield.json output_dir field (default docs/shield), {feature} is the feature folder ({feature-name}-YYYYMMDD), {date} is today's ISO date (YYYY-MM-DD), and {_counter} is empty for the first run of the day or _2, _3, ... on same-day collisions. Numbered-run subfolders (prd-review/{N}-{slug}/) are gone. Reviews never overwrite prior runs.
Resolving the counter: before writing, list {output_dir}/{feature}/reviews/prd/ for entries matching today's date. If {date}/ does not exist, use _counter="". Otherwise, find the highest {date}_<N>/ and use _counter="_<N+1>". Do NOT use any other path. The Write tool creates directories automatically.
When to Use
- User invokes
/prd-review with a PRD source (file path, URL, or paste)
- User asks "review my PRD" / "what's wrong with this PRD" / "PRD gap analysis"
When NOT to Use
- Plan review (technical breakdown / stories) — use
/plan-review instead
- Research review — use the research workflow's PM-review mode
- Code review — use
/review
Step Skeleton
At startup, call execute-steps to register these steps. Execute them in order, updating status after each.
| Step | Action | Condition | Mandatory |
|---|
| 1 | Classify input (local/URL/paste) — see ingest.md Step 1 | always | Yes |
| 2 | Resolve via resolver chain — see ingest.md Step 2 | URL only | URL only |
| 3 | Snapshot to source-prd.md — see ingest.md Step 3 | always | Yes |
| 4 | Detect PRD type, confirm with user — see ingest.md Step 4 | always | Yes |
| 5 | Dispatch the 14 entries from dimensions.md in parallel (9 skill-internal PM prompts + 4 legacy persona dispatches) | always | Yes |
| 6 | Aggregate grades + compute composite + apply P0-gate — see scoring.md | always | Yes |
| 7 | Generate enhanced-prd.md with inline annotations | always | Yes |
| 8 | Write summary.md, review-comments.json, detailed/.md | always | Yes |
| 9 | Update manifest.json, regenerate index.html dashboard | always | Yes |
| 10 | Offer apply options (use as canonical / convert back / skip) | always | Yes |
Workflow
1. Read context
- Read
.shield.json for: output_dir (default docs/shield), prd_review_personas (default all 5), prd_ingest_resolvers (default [])
- Determine feature folder context:
--feature <name> flag, or --name, or fall back to a prompt asking the user
2. Ingest
Follow ingest.md Steps 1-3:
- Classify input (local path / URL / paste)
- Route through resolver chain if URL
- Snapshot result to
{review_dir}/source-prd.md (where {review_dir} = {output_dir}/{feature}/reviews/prd/{date}{_counter} resolved per the Output Path section above)
3. Type detection + confirmation
Follow ingest.md Step 4. Confirm with user. Note: PRD-type override is per-invocation, not configured.
4. Dispatch (parallel — mixed pattern)
Read dimensions.md for the 14-entry dispatch registry. Two dispatch patterns coexist:
- Skill-internal prompts (rows 1, 2, 3, 7, 8, 9, 10, 11, 12 — all PM dims): read the prompt
file at
prompts/<name>.md, then dispatch a general-purpose Agent with that prompt content +
prd_path and prd_type inputs. The agent returns one dim-block JSON.
- Legacy persona dispatches (rows 4, 5+6, 13, anti-patterns): dispatch the named subagent via
subagent_type: <agent-id> (e.g. shield:agile-coach, shield:architect, shield:finops-analyst,
shield:dx-engineer) with the per-persona prompt skeleton kept inline below. shield:architect
is dispatched ONCE and grades both dim 5 and dim 6 in its returned envelope.
Critical: dispatch all 13 unique invocations in a single response (parallel). Aggregating
after waits.
Legacy-persona dispatch prompt skeleton (substitute per row):
You are reviewing a PRD in PRD-Review mode. Mode: Standalone.
**PRD source:** {source-prd.md path}
**PRD type:** {standard | lean — confirmed by user}
**Your assigned dimensions:** {list from dimensions.md row}
**Rubric:** Read `shield/skills/general/prd-review/rubric.md` for evaluation points per
dimension, severity model, and grade scale. Read `shield/skills/general/prd-review/scoring.md`
for the A-F → composite logic.
**Your job:**
1. Read the PRD at the path above.
2. For each of YOUR assigned dimensions, grade each evaluation point A-F (or N/A with
reasoning, or informational for lean dims).
3. Aggregate to a per-dimension grade.
4. Identify gaps — for each non-A grade, write a one-sentence gap description.
5. For each gap, suggest a fix (one or two sentences) suitable for `enhanced-prd.md`
annotation.
**Output format:** Return JSON in the per-persona envelope:
{
"persona": "<your agent id>",
"persona_grade": "A|B|C|D|F",
"dimensions": [
{ "id": <int>, "name": "...", "grade": "A|B|C|D|F|N/A|informational", "na_reasoning": "...",
"evaluation_points": [ {"id": "Na", "grade": "...", "severity": "...", "gap": "...", "suggestion": "..."} ] }
],
"anti_patterns": [ {"name": "...", "evidence_line": 42, "evidence_quote": "..."} ] // DX only
}
Special instructions per legacy persona (unchanged from the deprecated personas.md):
- Agile-coach (dim 4): apply AC1-AC12 framework including persona-goal coverage (consume
shield:story-coverage skill) and archetypal-flow coverage.
- Tech-lead / architect (dims 5, 6): treat 5b/5e as Critical for any feature with user data,
Important for purely internal infra. Grade dim 5 and dim 6 in one dispatch.
- DX (anti-patterns): primary output is the
anti_patterns array; no numeric dim.
- Cost / finops-analyst (dim 13): N/A allowed for clearly internal-only features (e.g.,
internal-tool fixture) with reasoning.
5. Aggregate
Collect dim-blocks from all 13 dispatch results. Two envelope shapes coexist:
- Per-dim envelope (skill-internal prompts): the returned JSON IS the dim-block — use directly.
- Per-persona envelope (legacy personas): unwrap the
dimensions[] array; each element is a
dim-block. Also capture anti_patterns[] from the DX dispatch.
Group dim-blocks by their owning persona (per dimensions.md's "Owning persona" column).
Then apply scoring.md:
- Per-dimension grade (already in each dim-block)
- Per-persona grade (compute by averaging the persona's dim-blocks numerically; for
product-manager,
this means averaging the 9 PM dim-blocks since the omnibus persona-grade is no longer emitted)
- Composite weighted average across activated personas
- Detect P0s (any Critical eval point graded D or F)
- Apply P0-gate to verdict
6. Generate enhanced-prd.md
For each gap-with-suggestion in the aggregated JSON:
- P0 or P1: insert inline in the relevant section of source-prd.md content; wrap with
<!-- [from: <Persona>] --> attribution
- P2: insert as a comment block adjacent to the relevant section, prefixed
<!-- Suggestion (<Persona>): ... -->
- Informational: insert as comment with
<!-- [informational] --> tag
Preserve source-prd.md's exact structure; only ADD content, never replace.
Write the result to enhanced-prd.md.
7. Write output artifacts
| File | Content |
|---|
summary.md | Scored analysis (template in templates.md if you create one, or follow the shape in the spec's Architecture summary) |
source-prd.md | (already written by Step 2) |
enhanced-prd.md | (Step 6 output) |
review-comments.json | Aggregated JSON conforming to the schema in spec's "Enhanced PRD output and comments export" section |
detailed/pm-reviewer.md | PM persona's full report (markdown rendering of their JSON, kept for skeptics) |
detailed/agile-coach.md | Agile-coach persona's full report |
detailed/tech-lead-reviewer.md | Tech-lead persona's full report |
detailed/dx-reviewer.md | DX persona's anti-pattern findings + clarity notes |
detailed/finops-analyst.md | Cost persona's full report |
7b. Render review HTML
Render summary.md and enhanced-prd.md into {review_outputs_dir} via the shared shell, then refresh the manifest-derived page assets:
"$CLAUDE_PLUGIN_ROOT/scripts/render-markdown.sh" \
--md {review_dir}/summary.md \
--shell "$CLAUDE_PLUGIN_ROOT/templates/shell.html" \
--out {review_outputs_dir}/summary.html \
--assets-root "{output_dir}" \
--title "Review — {feature}"
"$CLAUDE_PLUGIN_ROOT/scripts/render-markdown.sh" \
--md {review_dir}/enhanced-prd.md \
--shell "$CLAUDE_PLUGIN_ROOT/templates/shell.html" \
--out {review_outputs_dir}/enhanced-prd.html \
--assets-root "{output_dir}" \
--title "Review — {feature}"
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.
8. Update manifest + dashboard
- Append a new entry to
{output_dir}/manifest.json
- Regenerate
{output_dir}/index.html to show the new review with verdict badge
9. Offer apply options
Emit to user (template):
PRD Review complete.
Verdict: <Ready | Needs Work (composite X.X, blocked by N P0s) | Not Ready>
Files written:
- summary.md — scored analysis
- enhanced-prd.md — your PRD with suggested fixes applied
- review-comments.json — machine-readable for converters
- detailed/<persona>.md — per-reviewer findings
What next?
1. **Use enhanced as canonical PRD** — copy `{review_enhanced}` to `{prd}` (i.e. `{output_dir}/{feature}/prd.md`) so downstream Shield commands consume the fixed version
2. **Convert back to original format** — produce `enhanced-prd.<ext>` in source's format (HTML / Notion-flavored markdown)
3. **Skip** — keep `{review_enhanced}` in `{review_dir}`; do nothing else
User picks; Shield executes.
Common Mistakes
| Mistake | Fix |
|---|
| Dispatching reviewer agents sequentially | Dispatch all 13 unique invocations in a single response (parallel) |
| Writing review output to the wrong path | Must be {review_dir} = {output_dir}/{feature}/reviews/prd/{date}{_counter}/ — never the legacy prd-review/{N}-{slug}/, never shield/ or .shield/ |
| Overwriting source-prd.md after dispatch | Source snapshot is immutable; only enhanced-prd.md gets annotated |
| Skipping P0-gate when verdict has P0 + high composite | Verdict is Needs Work regardless of composite if any P0 exists |
| Producing enhanced-prd.md without inline attribution | Every P0/P1 inline edit MUST have <!-- [from: <Persona>] --> attribution |
| Auto-generating review-comments.md | Don't — JSON is canonical, markdown view is summary.md (per spec's drop-review-comments-md decision) |
See Also
ingest.md — input classification + resolver chainrubric.md — 13 dimensions, evaluation points, severity modeldimensions.md — 14-entry dispatch registry (replaces the old persona-keyed table)prompts/*.md — 9 skill-internal PM dim prompts (Pattern B)scoring.md — A-F → composite + P0-gate (accepts both envelope shapes)
