| name | prd-review |
| description | Use when a PRD is finished and about to be implemented by an autonomous AI agent (e.g. before /prd-run), or when asked to review/critique/stress-test a PRD or spec for AI-implementability. Triggers on "/prd-review", "review this PRD", "PRD'yi incele", "spec sağlam mı", "prd-run'dan önce kontrol et", "is this spec ready for the agent", "critique my PRD". Catches ambiguity, non-binary AC, missing protection list, and unsound assumptions BEFORE expensive implementation. |
| license | MIT |
| metadata | {"author":"murat-aydogan","version":"1.0"} |
prd-review
Reviews a PRD before any code is written, when the implementer is an
autonomous AI agent (vibe coding). The cheapest place to catch a defect is the
spec, not the diff. An agent does not resolve ambiguity — it amplifies it:
it fabricates the data model, the update cadence, and the pass criteria you
left vague. This skill makes the spec carry its own weight before
/prd-run turns it into code.
This skill does three things a generic read cannot do consistently:
- Convention discipline — checks the spec-first-feature rules (L107 binary
AC, L114 §6 schema categorization, L081 ≤8 deliverable/phase, L108 citation
existence) at draft time instead of waiting for PR time.
- AI-implementability — checks the things autonomous agents specifically
need and humans get away with omitting: a protection list, pinned
dependencies, predicate-shaped AC, explicit out-of-scope.
- Adversarial pass — invokes
prd-devils-advocate to attack the spec's
assumptions, run a pre-mortem, and audit its evidence.
Output is a scored, read-only report by default. A fix mode is opt-in.
When to use
- The user finished a PRD and is about to run
/prd-run (review it first).
- The user asks to review, critique, or stress-test a PRD / spec / feature design.
- Anyone says "is this ready for the agent" / "spec sağlam mı" / "prd-run'dan önce".
When NOT to use: reviewing a PR (code already written) → that is
review-project. Generic idea critique with no PRD → that is the-fool.
Inputs
- PRD file path (required). If not given, look for
docs/prd-*.md /
docs/*-prd.md and ask which.
- Fix mode? (optional). Defaults OFF (review-only). User opts in with
"fix the findings" / "apply fixes" / "--fix".
Phase 0 — Detect
Read the PRD. Decide its type:
- spec-first-feature PRD — has
§/Faz section structure (§0 Review Log …
§18 Research, or a subset). Run the full convention checklist.
- Generic PRD — no such structure. Skip convention-specific rules (L107
IDs etc.) and run only the structure + vibe-coding checks, adapted.
Never fabricate sections that do not exist; report them as missing, not as
violations of a convention the doc never adopted.
Phase 1 — Structure & completeness
For a spec-first-feature PRD, every load-bearing section must be present AND
substantive (a heading with "(doldurulacak)" / "TBD" / "Yok" under it counts as
missing, not present):
§1 Goal · §2 Non-goals · §5 Architecture · §6 Data model · §10 Phases ·
§11 Acceptance criteria · §12 Risk register · §12.5 Failure modes ·
§13 Edge cases · §15 Out of scope · §17 Open questions.
Missing or placeholder = finding. See references/discipline-checklist.md.
Phase 2 — Discipline checks (convention)
Run the rules in references/discipline-checklist.md: L107 (every AC binary),
L114 (§6 schema categorized var-tam / var-eksik / yok), L081 (≤8 deliverables
per phase), L108 (every file:line citation exists in the repo). Each
violation is a finding with the rule ID.
Phase 3 — AI-implementability (vibe coding)
Run references/vibe-coding-checklist.md: predicate-shaped AC, protection
list ("do not change" — schema, auth, public API signatures), pinned
dependencies (anti-hallucination), quantified thresholds, explicit error/edge
paths, modular phases with stated interdependencies. These are the checks a
human-oriented review skips and an autonomous agent pays for.
Phase 4 — Adversarial pass
REQUIRED SUB-SKILL: invoke prd-devils-advocate on the same PRD. It runs
three frameworks (pre-mortem, assumption-attack, evidence-audit) and returns
counter-arguments mapped to PRD sections (§12 risk, §12.5 failure modes, §17
open questions). Fold its findings into the report under "Devil's Advocate".
Report
Assemble per references/report-template.md: a decision
(APPROVE / CHANGES REQUESTED / BLOCKER), an AI-readiness score
(0–100), findings grouped P0 (blocks implementation) / P1 / P2, an AC-by-AC
table (binary? predicate? verifiable?), the devil's-advocate counter-arguments,
and a fix-routing table (AUTO_FIX / NEEDS_DECISION / MANUAL).
Scoring gate: any P0 → decision is at best CHANGES REQUESTED. A missing
protection list, a non-binary AC, or an undefined §6 schema is always P0 —
these are exactly what an autonomous agent fabricates.
Fix mode (opt-in only)
Only if the user opted in. Apply mechanical fixes with per-fix approval:
rewrite a non-binary AC into a predicate, add a missing-section skeleton,
add a protection-list stub. Never invent product decisions (those are
NEEDS_DECISION — surface, do not fix). Never commit, never push — Golden
Rule §6. Edit the PRD file in place; the user reviews the diff.
Common mistakes
- Reviewing prose quality instead of implementability. A beautifully-written
PRD with non-binary AC still fails the agent.
- Skipping Phase 4 because Phases 1–3 found enough. The adversarial pass
catches unsound specs that are structurally complete.
- "Approving" with open P0s because the doc looks thorough. Score the gate.
- Fixing a NEEDS_DECISION as if it were mechanical. If it encodes a product
choice (which table, what threshold), surface it — do not decide it.
