doc-prd-validator

Validate Product Requirements Documents (PRD) against Layer 2 MVP schema standards.

Purpose

Validates PRD documents for:

• YAML frontmatter metadata compliance
• Section structure (17 sections for MVP template)
• Document Control completeness
• Traceability tag format and presence
• Dual scoring requirements (SYS-Ready + EARS-Ready)
• File naming conventions

Activation

Invoke when:

• User requests validation of PRD documents
• After creating/modifying PRD artifacts
• Before generating downstream artifacts (EARS, BDD, ADR)
• As part of quality gate checks

Schema Reference

Validation Checklist

1. Metadata Validation

Required custom_fields:
  document_type: ["prd", "template"]
  artifact_type: "PRD"
  layer: 2
  architecture_approaches: [array format]
  priority: ["primary", "shared", "fallback"]
  development_status: ["active", "draft", "deprecated", "reference"]

Required tags:
  - prd (or prd-template)
  - layer-2-artifact

Forbidden tag patterns:
  - "^product-requirements$"
  - "^product-prd$"
  - "^feature-prd$"

2. Structure Validation (MVP Template – 17 Sections)

Required Sections (MVP Template):

Section Format: ## N. Title (numbered H2 headings)

3. Document Control Required Fields

4. Dual Scoring Requirements

Both scores must be present and meet thresholds for downstream artifact generation.

5. File Naming Convention

Pattern: PRD-NN_{descriptive_slug}.md

• NN: 2+ digit number (01, 02, … 99, 100)
• descriptive_slug: lowercase with underscores

Examples:

• PRD-01_user_authentication.md (correct)
• PRD-001_feature.md (incorrect – use 2 digits minimum, expand only as needed)
• PRD-1_feature.md (incorrect – minimum 2 digits)

Sectioned PRD Pattern: docs/PRD/PRD-NN_{slug}/PRD-NN.S_{section}.md

6. Traceability Validation

Layer 2 Cumulative Tags (Required):

@brd: BRD.NN.TT.SS

Unified Element ID Format:

Deprecated Patterns (Do NOT use):

• US-NNN → Use PRD.NN.09.SS
• FR-NNN → Use PRD.NN.01.SS
• AC-NNN → Use PRD.NN.06.SS
• F-NNN → Use PRD.NN.22.SS

Same-Type References:

• @related-prd: PRD-NN
• @depends-prd: PRD-NN

Downstream Expected:

• EARS statements (Layer 3)
• BDD scenarios (Layer 4)
• ADR documents (Layer 5)

7. Content Validation

User Story Format (Section 7):

• Pattern: PRD.NN.09.SS
• Format: “As a [role], I want [capability] so that [benefit]”
• Must include layer separation scope note

Functional Requirement Format (Section 8):

• Pattern: PRD.NN.01.SS
• Required fields: ID, Requirement, Priority, Acceptance Criteria
• Priority values: P1 (Must Have), P2 (Should Have), P3 (Could Have), P4 (Won’t Have)

Error Codes

Validation Commands

# Validate single PRD document (must be in nested folder)
python ai_dev_flow/scripts/validate_prd.py docs/02_PRD/PRD-01_example/PRD-01_example.md

# Validate all PRD documents in directory
python ai_dev_flow/scripts/validate_prd.py docs/02_PRD/

# Validate with verbose output
python ai_dev_flow/scripts/validate_prd.py docs/02_PRD/ --verbose

# Validate with auto-fix (includes structure fixes)
python ai_dev_flow/scripts/validate_prd.py docs/02_PRD/ --auto-fix

# Cross-document validation
python ai_dev_flow/scripts/validate_cross_document.py --document docs/02_PRD/PRD-01_slug/PRD-01_slug.md --auto-fix

# Layer-wide validation
python ai_dev_flow/scripts/validate_cross_document.py --layer PRD --auto-fix

Validation Workflow

1. Validate folder structure (CRITICAL – must be in docs/02_PRD/PRD-NN_{slug}/)
2. Parse YAML frontmatter
3. Check required metadata fields (document_type, artifact_type, layer)
4. Validate tag taxonomy (prd, layer-2-artifact)
5. Verify section structure (1-17 for MVP)
6. Validate Document Control table completeness
7. Check dual scoring (SYS-Ready + EARS-Ready ≥85%)
8. Validate upstream @brd reference format
9. Check element ID format (PRD.NN.TT.SS)
10. Detect deprecated patterns (US-NNN, FR-NNN)
11. Verify file naming convention
12. Generate validation report

Structure Validation (Step 1)

Nested Folder Rule: ALL PRDs MUST use nested folders regardless of size.

Validation Logic:

def validate_prd_structure(prd_path: str) -> list[Error]:
    errors = []

    # Extract PRD ID from filename
    filename = os.path.basename(prd_path)
    match = re.match(r'PRD-(\d+)_([^/]+)\.md', filename)

    if not match:
        errors.append(PRD_E001)  # Invalid filename
        return errors

    prd_id = match.group(1)
    slug = match.group(2)

    # Check parent folder
    parent_folder = os.path.dirname(prd_path)
    expected_folder = f"PRD-{prd_id}_{slug}"

    if os.path.basename(parent_folder) != expected_folder:
        errors.append(PRD_E020)  # Not in nested folder

    # Verify folder is under docs/02_PRD/
    if "/docs/02_PRD/" not in prd_path:
        errors.append(PRD_E020)  # Wrong base path

    return errors

Auto-Fix Actions

Integration

• Invoked by: doc-flow, doc-prd (post-creation), doc-prd-autopilot
• Feeds into: trace-check (cross-document validation)
• Reports to: quality-advisor

Output Format

PRD Validation Report
=====================
Document: PRD-01_user_authentication.md
Status: PASS/FAIL

Scores:
  SYS-Ready:  92% (Target: ≥85%) ✓
  EARS-Ready: 88% (Target: ≥85%) ✓

Errors: 0
Warnings: 2
Info: 1

[PRD-W001] WARNING: File name should use lowercase slug
[PRD-W004] WARNING: Missing Document Revision History table
[PRD-I001] INFO: Consider adding quantified success metrics

Related Resources

• Naming Standards: .claude/skills/doc-naming/SKILL.md (element IDs, threshold tags)
• PRD Skill: .claude/skills/doc-prd/SKILL.md
• PRD Template: ai_dev_flow/02_PRD/PRD-MVP-TEMPLATE.md
• PRD Schema: ai_dev_flow/02_PRD/PRD_MVP_SCHEMA.yaml
• Creation Rules: ai_dev_flow/02_PRD/PRD_MVP_CREATION_RULES.md
• Validation Rules: ai_dev_flow/02_PRD/PRD_MVP_VALIDATION_RULES.md
• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

Version History