doc-adr-validator Skill

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.

Agent Skills: doc-adr-validator

Install this agent skill to your local

Skill Files