PRD Validator

Runs automatically as Phase 1.5, between PRD generation and TechSpec generation. Purpose: catch problems in the PRD before they propagate into the TechSpec and Tasks.

Position in flow

[Prompt Enrichment]
      ↓
PRD generation
      ↓
[PRD Validation]  ← THIS SKILL
      ↓
TechSpec generation

Entry conditions

• prd.md

  must exist in

  tasks/prd-{slug}/

  (run PRD generation first)
• Generates

  prd-validation.md

  and saves to

  .claude/feature-state/{slug}/

• Load if already exists (resume flow)
• Can be forced with

  --revalidate

Validation 1: Reference Existence

Grep the codebase for every entity, service, path, endpoint, and component mentioned in the PRD.

What to check

• Services/classes: e.g., "uses the existing UserService" → grep for

  UserService

• API endpoints: e.g., "/api/users/connect" → grep for

  users/connect

  or

  usersConnect

• Database collections/tables: e.g., "connections collection" → grep for

  connections

• UI components: e.g., "TrainerCard component" → grep for

  TrainerCard

• File paths: explicit paths mentioned → check they exist with Glob

Classification

• Found in codebase → ✅ Pass
• Not found, but PRD says "will be created" → ⚠️ Warning (document as new entity)
• Not found, PRD implies it exists → ❌ Blocker (misleading reference)

Search commands

# For each entity/service name extracted from PRD:
grep -r "{term}" . \
  --include="*.ts" --include="*.tsx" --include="*.swift" \
  --include="*.rs" --include="*.py" --include="*.go" \
  -l 2>/dev/null | head -10

Validation 2: Scope Realism

Requirement count

• Count bullet points or numbered items in functional requirements sections
• ≤8 requirements → ✅ Manageable
• 9–15 requirements → ⚠️ Warning: "This is a larger scope. Consider splitting into phases."
• >15 requirements → ❌ Blocker: "Scope too large. Break into sub-features."

Scope creep word detection

Scan for phrases that inflate scope without commitment:

also

besides

additionally

in the future

eventually

later

it would be nice

ideally

if possible

real-time

live

instant

all

every

any

unlimited

Comparison with existing features

If

context.md

Validation 3: Acceptance Criteria Quality

For each AC in the PRD, classify as measurable or vague:

Vague AC patterns (flag these)

Measurable AC patterns (accept these)

Auto-fix suggestions for vague ACs

When a vague AC is detected, propose a measurable version:

Validation 4: Non-Goals Section

• PRD contains a

  Non-Goals

  ,

  Out of Scope

  , or

  YAGNI

  section → ✅ Pass
• PRD missing any such section → ❌ Blocker

When blocking on missing Non-Goals, suggest a starter list based on common exclusions for the detected feature type (from prompt-enricher keywords):

**Suggested Non-Goals for [feature type]:**
- [Context-appropriate exclusion 1]
- [Context-appropriate exclusion 2]
- [Context-appropriate exclusion 3]

Validation 5: Conflict with Existing PRDs

Scan

tasks/prd-*/prd.md

1. Extract the top 5 keywords from the current PRD's title and goals
2. Check if any existing PRD contains ≥3 of those keywords
3. If overlap found:
   • ⚠️ Warning: "PRD

     prd-{other-slug}

     covers similar domain. Review for conflicts."
   • List the overlapping keywords

Behavior

User interaction for blockers

❌ PRD Validation Failed — cannot proceed to TechSpec

Blocker 1: AC #3 is not measurable
  Current: "the system should feel responsive"
  Suggested fix: "page loads within 2 seconds on 3G connection"

Blocker 2: No Non-Goals section found
  Suggested Non-Goals:
  - Email notifications (requires separate notification service)
  - Mobile app changes (this feature is web-only)
  - Bulk operations (out of scope for v1)

Would you like me to apply these fixes to the PRD? [Yes / Let me fix manually / Show full report]

User interaction for warnings only

⚠️ PRD Validation — warnings found (non-blocking)

• Scope may be large (13 functional requirements)
• "UserService" referenced but not found in codebase — confirm it will be created
• "In the future, add analytics" → move this to Deferred section

Continue to TechSpec generation? [Yes, continue / Let me address these first]

Output: prd-validation.md

Save to

.claude/feature-state/{slug}/prd-validation.md

## PRD Validation Report

Generated: {timestamp}
PRD: tasks/prd-{slug}/prd.md

### ✅ Passed
- Acceptance criteria are measurable
- Non-goals section present
- Scope is within reasonable bounds (7 requirements)

### ⚠️ Warnings (non-blocking)
- Scope may be large (12 functional requirements)
- "UserService" referenced but not found in codebase (will be created as new entity)
- Scope creep phrase detected: "In the future, add analytics" → move to Deferred

### ❌ Blockers (must fix before proceeding)
- AC #3 is not measurable: "system should feel responsive"
  → Suggested: "page loads within 2 seconds on 3G connection"
- No Non-Goals section found
  → Suggested Non-Goals: [list]

### Reference Check
| Entity | Found in codebase? | Notes |
|--------|--------------------|-------|
| UserService | ❌ Not found | Marked as new creation in PRD |
| /api/users | ✅ Found | src/api/users.ts |
| TrainerCard | ✅ Found | Presentation/Features/Trainer/ |

### Scope Analysis
- Functional requirements: 12
- Scope creep phrases: 1 ("in the future")
- Similar feature: prd-student-enrollment had 6 requirements → this is ~2x larger

### AC Quality
| AC | Classification | Issue |
|----|----------------|-------|
| AC-1: returns 404 when not found | ✅ Measurable | — |
| AC-2: fast response | ❌ Vague | "fast" is not quantified |
| AC-3: users can connect | ⚠️ Borderline | Add: "within 2 clicks from the dashboard" |

### Verdict
BLOCKED — fix 2 blocker(s) before proceeding to TechSpec generation.

Integration with spec-writer

When

prd-validation.md

• Use the Reference Check table to know which entities are NEW vs EXISTING
• Use Scope Analysis to calibrate TechSpec complexity
• Reference the passed ACs as the baseline for implementation criteria