prd-review

Review the active PRD against templates/review-rubric.md. The rubric defines six dimensions (problem clarity, scope discipline, atomic decomposition, risk surface, dependencies, recurring gap classes) and the severity scale (blocker | major | minor | nit). Dimension 6 points at templates/gap-classes.md, the catalog of defect shapes that repeatedly ship past review.

Do not hand-edit the findings JSONL. Do not pass raw Codex output to the writer verbatim. The writer accepts ONLY {severity, body} objects; extra keys are rejected. This is the deterministic normalization layer — its whole purpose is to refuse drifted Codex output shape.

Steps:

1. Resolve the active PRD:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/prd_runner.py" status

Capture the prd_id and spec_path from the JSON output. If no PRD is active, stop and tell the author to run /prd-start first.

1. Read the PRD body, templates/review-rubric.md, and templates/gap-classes.md. Run Codex against all three (the gap-classes catalog is what dimension 6 evaluates against). Codex may return prose, markdown, or malformed JSON. That is expected.

2. Translate Codex's findings into the writer's input shape: a JSON array where every element is EXACTLY {"severity": "blocker|major|minor|nit", "body": "one concrete concern"}. One concern per element. No extra keys, no nesting. If Codex flagged the same concern twice, deduplicate.

3. Record the review.

   • If the array has at least one item, append via the writer. The writer assigns sequential ids, stamps created_at, sets disposition: pending, validates every field, AND stamps the PRD frontmatter with the review proof (codex_reviewed_at plus reviewed_by: <source>) as a side effect. That stamp is the approval gate's proof that a real reviewer ran:

   echo '<JSON_ARRAY>' | \
     python3 "${CLAUDE_PLUGIN_ROOT}/scripts/findings_writer.py" \
     add "<prd-id>" --source <SOURCE>
   

   • If the reviewer found nothing (clean pass), do NOT fabricate findings. Stamp the PRD with record-review so the approval gate can still fire:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/findings_writer.py" \
     record-review "<prd-id>" --source <SOURCE>
   

   <SOURCE> names the reviewer that actually ran. Never substitute one for another.

   Reviewer that ran	Standard pass	Adversarial pass
   Codex	codex-review	codex-adversarial
   Claude senior-staff-engineer subagent	claude-review	claude-adversarial

   Pick the row for the reviewer that ACTUALLY ran. Stamping codex-* for a pass Codex did not run puts a false provenance record in the findings ledger — worse than being blocked, in a repo whose whole thesis is receipts. If one reviewer is unavailable (no credits, missing auth), use another row and stamp what ran. Do NOT hardcode an outage into this file: a stale availability note outlives the outage and sends every later session to the wrong reviewer. manual and plan are the author's own words and the writer refuses them here by design.

   Without the stamp, /prd-approve will refuse to advance the PRD — that is the intended behavior. Do not try to work around it.

4. Advance the PRD to in-review so the findings gate will block approval:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/prd_runner.py" advance in-review

1. Tell the author to triage with /prd-triage. Show the count of new findings and the severity breakdown (or "0 findings, clean pass recorded" if the review was clean).