doc-adr-validator

Validate Architecture Decision Records (ADR) against Layer 5 schema standards.

Activation

Invoke when user requests validation of ADR documents or after creating/modifying ADR artifacts.

Validation Schema Reference

Schema: ai_dev_flow/ADR/ADR_SCHEMA.yaml Layer: 5 Artifact Type: ADR

Validation Checklist

0. Folder Structure Validation (BLOCKING)

Nested Folder Rule: ALL ADR documents MUST be in nested folders regardless of size.

Required Structure:

Validation:

1. Check document is inside a nested folder: docs/05_ADR/ADR-NN_{slug}/
2. Verify folder name matches ADR ID pattern: ADR-NN_{slug}
3. Verify file name matches folder: ADR-NN_{slug}.md
4. Parent path must be: docs/05_ADR/

Example Valid Structure:

docs/05_ADR/
├── ADR-01_f1_iam/
│   ├── ADR-01_f1_iam.md           ✓ Valid
│   ├── ADR-01.R_review_report_v001.md
│   └── .drift_cache.json
├── ADR-02_f2_session/
│   └── ADR-02_f2_session.md       ✓ Valid

Invalid Structure:

docs/05_ADR/
├── ADR-01_f1_iam.md               ✗ NOT in nested folder

Error Codes:

This check is BLOCKING - ADR must pass folder structure validation before other checks proceed.

1. Metadata Validation

Required custom_fields:
  - document_type: ["adr", "template"]
  - artifact_type: "ADR"
  - layer: 5
  - architecture_approaches: [array format]
  - priority: ["primary", "shared", "fallback"]
  - development_status: ["active", "draft", "deprecated", "reference"]

Required tags:
  - adr (or adr-template)
  - layer-5-artifact

Forbidden tag patterns:
  - "^architecture-decision$"
  - "^decision-record$"
  - "^adr-\\d{3}$"

2. Structure Validation

Document Parts:

• PART 1: Decision Context and Requirements (Sections 1-6)
• PART 2: Impact Analysis and Architecture (Sections 7-10)
• PART 3: Implementation Strategy (Sections 11-13)
• PART 4: Traceability and Documentation (Sections 14-15)

Required Sections:

• Title (H1): # ADR-NNN: Title
• Section 1: Document Control
• Section 2: Position in Development Workflow
• Section 3: Status
• Section 4: Context (Problem Statement, Background, Driving Forces, Constraints)
• Section 5: Decision (Chosen Solution, Key Components, Implementation Approach)
• Section 6: Requirements Satisfied
• Section 7: Consequences (Positive, Negative Outcomes)
• Section 8: Architecture Flow (Mermaid diagram)
• Section 9: Implementation Assessment (Complexity, Dependencies)
• Section 10: Impact Analysis

Optional Sections:

• Section 11: Alternatives Considered
• Section 12: Security Considerations
• Section 13: Operational Considerations
• Section 14: Traceability
• Section 15: References

Document Control Required Fields:

• Project Name
• Document Version
• Date
• Document Owner
• Prepared By
• Status

File Naming: Pattern: ADR-NNN_descriptive_name.md

3. Content Validation

Status Values:

• Proposed
• Accepted
• Deprecated
• Superseded

Context Subsections (Required):

• 4.1 Problem Statement
• 4.2 Background
• 4.3 Driving Forces
• 4.4 Constraints

Decision Subsections (Required):

• 5.1 Chosen Solution
• 5.2 Key Components
• 5.3 Implementation Approach

Consequences Subsections (Required):

• 7.1 Positive Outcomes
• 7.2 Negative Outcomes

Architecture Flow:

• Must contain Mermaid diagram
• Allowed types: flowchart, sequenceDiagram, stateDiagram-v2

ADR-Ready Score:

• Minimum threshold: 90%
• Components: Problem statement, context, decision clarity, consequences, architecture diagram, implementation assessment, traceability

4. Traceability Validation

Layer 5 Cumulative Tags:

• @brd: BRD.NN.01.SS (required)
• @prd: PRD.NN.07.SS (required)
• @ears: EARS.NN.24.SS (required)
• @bdd: BDD.NN.13.SS (required)

Downstream Expected:

• SYS requirements
• REQ documents
• SPEC documents

Same-Type References:

• @related-adr: ADR-NN
• @supersedes: ADR-NN
• @depends-adr: ADR-NN

Error Codes

Validation Commands

# Validate single ADR document
python ai_dev_flow/scripts/validate_adr.py docs/05_ADR/ADR-001_example.md

# Validate all ADR documents
python ai_dev_flow/scripts/validate_adr.py docs/05_ADR/

# Check with verbose output
python ai_dev_flow/scripts/validate_adr.py docs/05_ADR/ --verbose

Validation Workflow

1. Parse YAML frontmatter
2. Check required metadata fields
3. Validate tag taxonomy
4. Verify 4-part structure
5. Validate required sections (1-10)
6. Check Context subsections
7. Check Decision subsections
8. Check Consequences subsections
9. Verify Mermaid diagram presence
10. Validate upstream references
11. Calculate SYS-Ready Score
12. Verify file naming convention
13. Generate validation report

Integration

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

Output Format

ADR Validation Report
=====================
Document: ADR-001_example.md
Status: PASS/FAIL

Structure:
- Context: Complete/Incomplete
- Decision: Complete/Incomplete
- Consequences: Complete/Incomplete
- Architecture Flow: Present/Missing

Errors: N
Warnings: N
Info: N

[Details listed by severity]

Version History