Prd Validator

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:

Comparison with existing features

If context.md exists, compare requirement count with similar implemented features. If similar feature had 6 tasks and this PRD has 18 requirements → flag the discrepancy.

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 for other PRDs that cover the same domain:

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 exists and has no blockers, spec-writer reads it for context:

• 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