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_ssd_flow/05_ADR/ADR_MVP_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:

ADR Type Required Location

Monolithic docs/05_ADR/ADR-NN_{slug}/ADR-NN_{slug}.md

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.A_audit_report_v001.md │ ├── ADR-01.R_review_report_v001.md (legacy) │ └── .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:

Code Severity Description

ADR-E020 ERROR ADR not in nested folder (BLOCKING)

ADR-E021 ERROR Folder name doesn't match ADR ID

ADR-E022 ERROR File name doesn't match folder name

VAL-H001 ERROR Drift cache missing hash for upstream document

VAL-H002 ERROR Invalid hash format (must be sha256:<64 hex chars>)

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

MVP Template Structure (11 Sections):

Section Required Purpose

1 Document Control MANDATORY Metadata with SYS-Ready Score

2 Context MANDATORY Problem Statement, Technical Context

3 Decision MANDATORY Chosen Solution, Key Components, Approach

4 Alternatives Considered MANDATORY Options with pros/cons

5 Consequences MANDATORY Positive/Negative Outcomes, Costs

6 Architecture Flow MANDATORY Mermaid diagrams, Integration Points

7 Implementation Assessment MANDATORY Phases, Rollback, Monitoring

8 Verification MANDATORY Success Criteria, BDD Scenarios

9 Traceability MANDATORY Upstream/Downstream, Tags, Cross-Links

10 Related Decisions MANDATORY Dependencies, Supersessions

11 MVP Lifecycle MANDATORY Iteration guidance

Title (H1): # ADR-NN: Title

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

Code Severity Description

ADR-E001 error Missing required tag 'adr'

ADR-E002 error Missing required tag 'layer-5-artifact'

ADR-E003 error Invalid document_type

ADR-E004 error Invalid architecture_approaches format

ADR-E005 error Forbidden tag pattern detected

ADR-E006 error Missing required section

ADR-E007 error Multiple H1 headings detected

ADR-E008 error Missing Context section (Section 4)

ADR-E009 error Missing Decision section (Section 5)

ADR-E010 error Missing Consequences section (Section 7)

ADR-E011 error Context missing Problem Statement subsection

ADR-E012 error Decision missing Chosen Solution subsection

ADR-E013 error Consequences missing outcomes

ADR-E014 warning File name does not match format

ADR-W001 warning Missing Architecture Flow Mermaid diagram

ADR-W002 warning Context missing Constraints subsection

ADR-W003 warning Missing upstream tags (@prd, @ears, @bdd)

ADR-W004 warning Implementation Assessment missing Complexity

ADR-W005 warning SYS-Ready Score below 90%

ADR-W006 warning Requirements Satisfied table missing

ADR-I001 info Consider adding Alternatives Considered

ADR-I002 info Consider adding Security Considerations

ADR-I003 info Consider adding Rollback Plan

Validation Commands

Validate single ADR document

python ai_dev_ssd_flow/05_ADR/scripts/validate_adr.py docs/05_ADR/ADR-001_example.md

Validate all ADR documents

python ai_dev_ssd_flow/05_ADR/scripts/validate_adr.py docs/05_ADR/

Check with verbose output

python ai_dev_ssd_flow/05_ADR/scripts/validate_adr.py docs/05_ADR/ --verbose

Validation Workflow

• Parse YAML frontmatter

• Check required metadata fields

• Validate tag taxonomy

• Verify 4-part structure

• Validate required sections (1-10)

• Check Context subsections

• Check Decision subsections

• Check Consequences subsections

• Verify Mermaid diagram presence

• Validate upstream references

• Calculate SYS-Ready Score

• Verify file naming convention

• 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

Version Date Changes Author

1.3 2026-02-27 Migrated frontmatter to metadata ; normalized schema/command references to ai_dev_ssd_flow/05_ADR ; updated valid structure example for preferred ADR-NN.A_audit_report_vNNN.md with legacy reviewer compatibility System

1.2 2026-02-26 Updated structure validation to 11-section MVP template (aligned with ADR-MVP-TEMPLATE.md v1.1)

1.1 2026-02-11 Nested Folder Rule: Added Section 0 Folder Structure Validation (BLOCKING); ADR must be in docs/05_ADR/ADR-NN_{slug}/ folders; Added error codes ADR-E020, ADR-E021, ADR-E022

1.0 2026-02-08 Initial validator skill definition with YAML frontmatter System

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 .