doc-ears-validator

Validate EARS (Easy Approach to Requirements Syntax) documents against Layer 3 schema standards.

Activation

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

Validation Schema Reference

Schema: ai_dev_flow/EARS/EARS_SCHEMA.yaml Layer: 3 Artifact Type: EARS

Validation Checklist

0. Folder Structure Validation (BLOCKING)

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

Required Structure:

Validation:

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

Example Valid Structure:

docs/03_EARS/
├── EARS-01_f1_iam/
│   ├── EARS-01_f1_iam.md          ✓ Valid
│   ├── EARS-01.R_review_report_v001.md
│   └── .drift_cache.json
├── EARS-02_f2_session/
│   └── EARS-02_f2_session.md      ✓ Valid

Invalid Structure:

docs/03_EARS/
├── EARS-01_f1_iam.md              ✗ NOT in nested folder

Error Codes:

This check is BLOCKING – EARS must pass folder structure validation before other checks proceed.

1. Metadata Validation

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

Required tags:
  - ears (or ears-template)
  - layer-3-artifact

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

2. Structure Validation

Required Sections:

• Title (H1): # EARS-NNN: Title
• Document Control (Section 1)
• Requirements Summary (Section 2)
• Ubiquitous Requirements (Section 3)
• Event-Driven Requirements (Section 4)
• State-Driven Requirements (Section 5)
• Unwanted Behavior Requirements (Section 6)
• Optional Feature Requirements (Section 7)
• Complex Requirements (Section 8)
• Traceability (Section 9)
• Change History (Section 10)

Document Control Required Fields:

• EARS ID
• Document Name
• Version
• Date Created
• Last Updated
• Author
• Status
• Source PRD

File Naming: Pattern: EARS-NNN_descriptive_name.md

3. Content Validation

EARS Requirement Patterns:

Requirement ID Format:

• Pattern: EARS.NN.EE.SS (4-segment format)
• Example: EARS.01.24.01

BDD-Ready Score:

• Minimum threshold: 90%
• Components: Pattern compliance, requirement clarity, testability, traceability

4. Traceability Validation

Layer 3 Cumulative Tags:

• @brd: BRD.NN.01.SS (required)
• @prd: PRD.NN.07.SS (required)

Downstream Expected:

• BDD scenarios
• ADR documents
• SYS requirements

Same-Type References:

• @related-ears: EARS-NN
• @depends-ears: EARS-NN

Error Codes

Validation Commands

# Validate single EARS document
python ai_dev_flow/scripts/validate_ears.py docs/03_EARS/EARS-001_example.md

# Validate all EARS documents
python ai_dev_flow/scripts/validate_ears.py docs/03_EARS/

# Check with verbose output
python ai_dev_flow/scripts/validate_ears.py docs/03_EARS/ --verbose

Validation Workflow

1. Parse YAML frontmatter
2. Check required metadata fields
3. Validate tag taxonomy
4. Verify section structure (1-10)
5. Validate Document Control table
6. Check EARS pattern compliance
7. Verify SHALL/SHOULD/MAY keywords
8. Validate upstream references
9. Calculate BDD-Ready Score
10. Verify file naming convention
11. Generate validation report

EARS Pattern Detection

patterns = {
    'ubiquitous': r'^The\s+\[?\w+\]?\s+SHALL\s+',
    'event_driven': r'^WHEN\s+.+\s+THE\s+\[?\w+\]?\s+SHALL\s+',
    'state_driven': r'^WHILE\s+.+\s+THE\s+\[?\w+\]?\s+SHALL\s+',
    'unwanted': r'^IF\s+.+\s+THEN\s+THE\s+\[?\w+\]?\s+SHALL\s+',
    'optional': r'^WHERE\s+.+\s+IS\s+SUPPORTED\s+THE\s+\[?\w+\]?\s+SHALL\s+'
}

Integration

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

Output Format

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

Pattern Compliance:
- Ubiquitous: N requirements
- Event-Driven: N requirements
- State-Driven: N requirements
- Unwanted: N requirements
- Optional: N requirements

Errors: N
Warnings: N
Info: N

[Details listed by severity]

Version History