doc-prd-validator（文档 prd 验证器）

doc-prd-validator

DEPRECATED (2026-03-02): This skill has been merged into doc-prd-audit as part of the 2-skill model standardization. Use doc-prd-audit for all PRD validation needs. This file is retained for reference only. Replacement: /doc-prd-audit Migration: No action required. Simply use doc-prd-audit instead of this skill.

Legacy Documentation (Reference Only)

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

Purpose

Validates PRD documents for:

• YAML frontmatter metadata compliance
• Section structure (21 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.xxxx

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

# Canonical wrapper (core only; pre-commit/CI parity)
bash ai_dev_ssd_flow/02_PRD/scripts/prd_core_wrapper_hook.sh ai_dev_ssd_flow/02_PRD

# Strict PRD ID checks (same quality class as BRD ID checks)
bash ai_dev_ssd_flow/02_PRD/scripts/prd_standardized_element_codes_hook.sh ai_dev_ssd_flow/02_PRD
bash ai_dev_ssd_flow/02_PRD/scripts/prd_legacy_pattern_hook.sh ai_dev_ssd_flow/02_PRD

# Canonical wrapper (core + advisory)
bash ai_dev_ssd_flow/02_PRD/scripts/validate_prd_wrapper.sh docs/02_PRD

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

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

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

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

# Cross-document validation
python ai_dev_ssd_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_ssd_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 ≥90%)
8. Validate upstream @brd reference format
9. Check element ID format (PRD.NN.xxxx)
10. Detect deprecated patterns (US-NNN, FR-NNN)
11. Validate diagram contract (C4-L2, DFD-L1, sequence tag, sequence exception path)
12. Validate diagram intent header fields
13. Verify file naming convention
14. 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: ≥90%) ✓
  EARS-Ready: 91% (Target: ≥90%) ✓

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_ssd_flow/02_PRD/PRD-MVP-TEMPLATE.md
• PRD Schema: ai_dev_ssd_flow/02_PRD/PRD_MVP_SCHEMA.yaml
• Creation Rules: ai_dev_ssd_flow/02_PRD/PRD-MVP-TEMPLATE.md
• Validation Rules: ai_dev_ssd_flow/02_PRD/PRD_MVP_SCHEMA.yaml
• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

Version History

Implementation Plan Consistency (IPLAN-004)

• Treat plan-derived outputs as valid source mode and verify intent preservation from implementation plan scope/objectives.
• Validate upstream autopilot precedence assumption: --iplan > --ref > --prompt.
• Flag objective/scope conflicts between plan context and artifact output as blocking issues requiring clarification.
• Do not introduce legacy fallback paths such as docs-v2.0/00_REF.