prd-validator

name	prd-validator
description	Use when a PRD.md exists and is about to be handed to engineering, fed into a roadmap, or declared "ready"; when the user asks "is this PRD ready", "validate my requirements", or "check this PRD"; when prd-author finishes a draft or iteration; or when a PRD arrived from a stakeholder and its quality is unknown

PRD Validator

Type: rigid (discipline). Follow exactly. Do not adapt away the gate or substitute judgment for the script.

Overview

A PRD that passes a real validation run is ready; one you eyeballed is a guess. Run the checker, read the score, fix the errors, re-run.

Core principle: a "ready" PRD is one that scored PASS on a fresh run THIS message — nothing less.

Violating the letter of the rules is violating the spirit of the rules.

The Iron Law

NO "PRD IS READY" CLAIM WITHOUT A PASSING validate_prd.py RUN THIS MESSAGE

Reading the PRD and judging it "looks complete" is not validation. A score from a previous message, a different file, or before your last edit does not count. The script run produces the evidence; nothing else does.

The Gate

1. LOCATE  Find the PRD. No path given -> check ./PRD.md; if absent, ask the user.
2. RUN     python scripts/validate_prd.py <path> --verbose
           Draft / work-in-progress: add --draft (threshold drops 70 -> 50).
3. READ    Full output: score, verdict, every ERROR, every WARNING.
4. VERIFY  PASS (>= threshold, zero errors)?
           - NO  -> fix each ERROR, then re-run from step 2. Do not hand off.
           - YES -> report the score with the evidence attached.
5. ONLY THEN call the PRD ready / proceed to roadmap.

Run from this skill's base directory so the relative scripts/ path resolves (the script is bundled alongside this file at scripts/validate_prd.py). Exit code 0 = PASS, 1 = NEEDS WORK.

Checks Performed (17)

#	Check	What it validates
1	Problem statement	Section exists and is substantive, not just a heading
2	User personas	Section exists with at least one persona
3	Persona detail	Each persona names goals and pain points
4	Functional requirements	Section exists with requirement descriptions
5	Requirement IDs	Consistent IDs present (FR-001 format)
6	Acceptance criteria	Requirements describe what "done" looks like
7	Non-functional requirements	Performance, security, scalability documented
8	Scope boundary	Both in-scope AND out-of-scope stated explicitly
9	Dependencies	External systems, teams, data, APIs documented
10	Milestones	Phased delivery plan exists
11	Milestone deliverables	Each milestone states what users can do when it ships
12	Vague language	Flags "TBD" w/o owner, "should work", "probably", "as needed", "etc."
13	Oversized code blocks	Code blocks > 15 lines (PRDs describe, not implement)
14	Success metrics	Measurable outcomes defined
15	Open questions	Unresolved items documented (or explicitly empty)
16	ID consistency	Requirement IDs follow one consistent format, no gaps
17	Implementation leakage	"Files to change", source paths, line refs belong in PLAN.md, not PRD

Red Flags — STOP

These thoughts or words mean stop and run the gate:

• "This PRD looks complete / thorough / ready" — without a run
• "I read it, the sections are all there" — eyeballing is not validating
• "It passed last time" / "I validated an earlier draft" — stale run
• "Close enough to hand off" with open ERRORs unresolved
• "I'll just report a score" you did not get from the script
• About to invoke prd-to-roadmap on a PRD you never validated this message
• "Skip the script, I know PRDs" — the script is the evidence, not your taste

Excuse → Reality

Excuse	Reality
"It looks complete"	Run the script. Looks are not a score.
"I read every section"	Reading is not validation. The checker finds what you skim past.
"It passed earlier"	Stale. Re-run on the current file THIS message.
"Just warnings, ship it"	ERRORs block; warnings are quality debt you decided to keep on purpose, not by default.
"Close enough for handoff"	A PRD with open ERRORs is not ready. Fix, then re-run.
"I'll report the score I expect"	Report only the score the script printed.
"Draft, so quality doesn't matter"	Use --draft (threshold 50). It still has to pass.
"Different words, so the gate doesn't apply"	Spirit over letter. "Ready", "good to go", "solid" all trigger it.

Good / Bad pairs

Reporting readiness:

✅ [Run validate_prd.py --verbose] [score 84/100, PASS, 0 errors] "PRD passes: 84/100"
❌ "The PRD looks complete and ready for engineering"

Handling failures:

✅ PASS at 58 -> fix the 3 ERRORs -> re-run -> 78/100 PASS -> hand off
❌ "Scored 58 but it's basically fine, sending it over"

Draft mode:

✅ [Run with --draft] [score 62/100, PASS at threshold 50] "Draft passes; warnings tracked for finalization"
❌ Run without --draft on a WIP PRD, report NEEDS WORK, give no path forward

Tracking

When the PRD scores NEEDS WORK, make each ERROR a TodoWrite entry, fix them, then re-run. Untracked fix lists get items skipped — every time.

Integration

• Called by constellation:prd-author — invoked automatically after a PRD is created or iterated. (REQUIRED SUB-SKILL for prd-author's completion gate.)
• Gates constellation:prd-to-roadmap — that skill refuses to proceed unless the PRD passed this validator. Do not enter roadmap translation on an unvalidated PRD.
• Tool portability (Codex tool names): see the plugin's skills/_shared/platform/codex-tools.md.

The Bottom Line

Run the script. Read the score. Fix the ERRORs. Re-run. Only a fresh PASS makes a PRD ready.