doc-brd-validator

Validate Business Requirements Documents (BRD) against Layer 1 MVP schema standards.

Validation Scope Contract: This skill is the structural/schema gate only. Deep semantic review (strategic alignment, content quality, unresolved placeholders, business consistency) is owned by doc-brd-reviewer.

Purpose

Validates BRD documents for:

• YAML frontmatter metadata compliance
• Section structure (18 sections for comprehensive template)
• Document Control completeness
• Traceability tag format and presence
• PRD-Ready scoring
• File naming conventions
• Architecture Decision Requirements completeness
• Diagram contract structural compliance (c4-l1, dfd-l0, sequence tags, intent header fields)

Activation

Invoke when:

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

Schema Reference

Non-Redundancy Boundary

Autopilot sequence remains: validator first, then reviewer/fixer loop.

Validation Checklist

1. Metadata Validation

Required custom_fields:
  document_type: ["brd", "template"]
  artifact_type: "BRD"
  layer: 1
  architecture_approaches: [array format]
  priority: ["primary", "shared", "fallback"]
  development_status: ["active", "draft", "deprecated", "reference"]

Required tags:
  - brd (or brd-template)
  - layer-1-artifact

Forbidden tag patterns:
  - "^business-requirements$"
  - "^brd-\\d{3}$"

2. Structure Validation

Required Sections (18 Total):

Section 14 Required Subsections:

• 14.1 Governance Structure
• 14.2 Decision Authority Matrix
• 14.3 Status Reporting
• 14.4 Change Control
• 14.5 Approval and Sign-off

Section 15 Required Subsections:

• 15.1 Quality Standards
• 15.2 Testing Strategy
• 15.3 Quality Gates

Section 16 Required Subsections:

• 16.1 Requirements Traceability Matrix
• 16.2 Cross-BRD Dependencies
• 16.3 Test Coverage Traceability
• 16.4 Traceability Summary

Section 17 Required Subsections (6 total):

• 17.1 Business Terms
• 17.2 Technical Terms
• 17.3 Domain-Specific Terms
• 17.4 Acronyms
• 17.5 Cross-References
• 17.6 External Standards

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

3. Document Control Required Fields

4. Content Validation

Business Objectives Format (Section 2):

• Pattern: BRD.NN.23.SS (unified 4-segment format)
• Required fields: ID, Objective, Priority, Success Criteria, Measurement Method

Business Requirements Format (Section 6):

• Pattern: BRD.NN.01.SS (unified 4-segment format)
• Required fields: ID, Requirement, Type, Priority, Source, Rationale
• Priority values: Critical (P1), High (P2), Medium (P3), Low (P4)
• Type values: Functional, Non-Functional, Regulatory, Operational

PRD-Ready Score:

• Minimum threshold: 90%
• Components: Business objectives, requirements completeness, success metrics, constraints, stakeholder analysis, risk assessment, traceability, ADR topics completeness

5. Architecture Decision Requirements (Section 7.2) – MANDATORY

7 Mandatory ADR Topic Categories:

Element Type Code: 32 = Architecture Topic (see doc-naming skill)

Required Fields Per Topic (Status=Selected):

• Status (Selected/Pending/N/A)
• Business Driver
• Business Constraints
• Alternatives Overview table (Option | Function | Est. Monthly Cost | Selection Rationale)
• Cloud Provider Comparison table (Criterion | GCP | Azure | AWS)
• Recommended Selection
• PRD Requirements

Required Fields Per Topic (Status=Pending):

• Status with reason
• Business Driver
• Business Constraints
• PRD Requirements

Required Fields Per Topic (Status=N/A):

• Status with explicit reason
• PRD Requirements (can be “None for current scope”)

6. Naming Compliance (doc-naming integration)

Element ID Validation:

• Format: BRD.NN.TT.SS (4-segment unified format)
• Valid element type codes for BRD: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 22, 23, 24, 32, 33
• No legacy patterns (BO-XXX, FR-XXX, AC-XXX, BC-XXX)

File Naming Convention:

• Pattern: BRD-NN_{descriptive_slug}.md
• NN: 2+ digit number (01, 02, … 99, 100)
• descriptive_slug: lowercase with underscores

Sectioned BRD Pattern: docs/01_BRD/BRD-NN_{slug}/BRD-NN.S_{section}.md

7. Traceability Validation

Layer 1 Tags:

• No upstream artifacts required (BRD is the entry point)
• Tag count: 0

Downstream Expected:

• PRD documents (Layer 2)
• EARS statements (Layer 3)
• ADR documents (Layer 5)

Same-Type References:

• @related-brd: BRD-NN
• @supersedes-brd: BRD-NN
• @depends-brd: BRD-NN

8. Upstream Source Configuration Validation

YAML Frontmatter Fields:

Validation Rules:

1. If upstream_mode not set: Valid (defaults to "none")
2. If upstream_mode: "none": upstream_ref_path ignored
3. If upstream_mode: "ref": upstream_ref_path should be set
4. If upstream_ref_path set: Validate path(s) exist

Path Validation:

• Resolve relative path from BRD file location
• Check directory exists
• Warn if directory empty

Default Behavior:

• BRDs without upstream_mode are treated as upstream_mode: "none"
• Drift detection is automatically skipped for these BRDs

8.1 Hash Format Validation

When upstream_mode: "ref" and .drift_cache.json exists, validate hash integrity.

Validation Checks:

Validation Algorithm:

# For each upstream document in drift cache:
# 1. Check valid hash format
grep -oP '"hash":\s*"sha256:[0-9a-f]{64}"' .drift_cache.json

# 2. Check for placeholder values (must return empty)
grep -E '"hash":\s*"(sha256:)?(verified_no_drift|pending_verification|TBD)"' .drift_cache.json

Validation Logic:

1. If upstream_mode: "none" → Skip hash validation
2. If .drift_cache.json missing → Skip (reviewer will create it)
3. If upstream_documents empty → Valid (no refs tracked)
4. For each entry in upstream_documents:
   • Check hash field exists → VAL-H001 if missing
   • Check hash format is valid → VAL-H002 if invalid or placeholder

9. Diagram Contract Validation

BRD diagram contract requirements follow ai_dev_ssd_flow/DIAGRAM_STANDARDS.md.

Advisory BRD tags:

• @diagram: c4-l1
• @diagram: dfd-l0

Conditional requirement:

• If any sequence diagram is present, at least one sequence contract tag should be present:
  • @diagram: sequence-sync
  • @diagram: sequence-async
  • @diagram: sequence-error

Diagram intent header fields (recommended for BRD diagram blocks):

• diagram_type
• level
• scope_boundary
• upstream_refs
• downstream_refs

Transition policy:

• BRD diagram checks are non-blocking advisories.
• Canonical blocking enforcement is in PRD validator (PRD-E023..PRD-E026).

Error Codes

Validation Commands

# Validate single BRD document
python ai_dev_ssd_flow/01_BRD/scripts/validate_brd.py docs/01_BRD/BRD-01_example.md

# Validate all BRD documents in directory
python ai_dev_ssd_flow/01_BRD/scripts/validate_brd.py docs/01_BRD/

# Validate with verbose output
python ai_dev_ssd_flow/01_BRD/scripts/validate_brd.py docs/01_BRD/ --verbose

# Validate with auto-fix
python ai_dev_ssd_flow/01_BRD/scripts/validate_brd.py docs/01_BRD/ --auto-fix

# Cross-document validation
python ai_dev_ssd_flow/scripts/validate_cross_document.py --document docs/01_BRD/BRD-01.md --auto-fix

Validation Workflow

1. Parse YAML frontmatter
2. Check required metadata fields (document_type, artifact_type, layer)
3. Validate tag taxonomy (brd, layer-1-artifact)
4. Verify section structure (18 sections)
5. Validate Document Control table completeness
6. Check business objectives format (BRD.NN.23.SS)
7. Check business requirements format (BRD.NN.01.SS)
8. Validate Section 7.2 ADR Topics:
   • Verify all 7 mandatory categories present
   • Check Status field (Selected/Pending/N/A)
   • For Selected: Verify Alternatives Overview table, Cloud Provider Comparison table
   • For N/A: Verify explicit reason provided
   • Validate element ID format (BRD.NN.32.SS)
9. Validate upstream source configuration:
   • Check upstream_mode value (valid: “ref”, “none”, or not set)
   • If upstream_mode: “ref”: Verify upstream_ref_path is set and paths exist
   • If upstream_mode: “none”: Skip upstream_ref_path validation
10. Validate diagram contract advisory compliance:

• Check recommended BRD tags @diagram: c4-l1 and @diagram: dfd-l0
• If sequence diagram exists, check for sequence contract tag
• Check diagram intent header fields

11. Calculate PRD-Ready Score (includes ADR completeness)
12. Verify file naming convention
13. Check element ID format compliance (per doc-naming)
14. Detect deprecated patterns
15. Generate validation report

Auto-Fix Actions

Integration

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

Output Format

BRD Validation Report
=====================
Document: BRD-01_platform_architecture.md
Status: PASS/FAIL

PRD-Ready Score: 92% (Target: ≥90%) ✓

Errors: 0
Warnings: 2
Info: 1

[BRD-W006] WARNING: File name should use lowercase slug
[BRD-W009] WARNING: Missing Document Revision History table
[BRD-I001] INFO: Consider adding regulatory compliance requirements

Related Resources

• Naming Standards: .claude/skills/doc-naming/SKILL.md (element IDs, element type codes)
• BRD Skill: .claude/skills/doc-brd/SKILL.md
• BRD Template: ai_dev_ssd_flow/01_BRD/BRD-MVP-TEMPLATE.md
• BRD Schema: ai_dev_ssd_flow/01_BRD/BRD_MVP_SCHEMA.yaml
• Creation Rules: ai_dev_ssd_flow/01_BRD/BRD_MVP_CREATION_RULES.md
• Validation Rules: ai_dev_ssd_flow/01_BRD/BRD_MVP_VALIDATION_RULES.md
• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

Version History