prd-review

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:

1. 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.
2. 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.
3. 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

1. PRD file path (required). If not given, look for docs/prd-*.md / docs/*-prd.md and ask which.
2. 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.