Skills
skills/vladm3105/aidoc-flow-framework/doc-ears-validator

doc-ears-validator

SKILL.md

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_ssd_flow/03_EARS/EARS_MVP_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:

EARS Type Required Location
Monolithic docs/03_EARS/EARS-NN_{slug}/EARS-NN_{slug}.md

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

Code Severity Description
EARS-E020 ERROR EARS not in nested folder (BLOCKING)
EARS-E021 ERROR Folder name doesn't match EARS ID
EARS-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 - 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 (6-Section MVP Structure):

  • Title (H1): # EARS-NN: Title
  • Document Control (unnumbered) - Metadata with BDD-Ready Score
  • Section 1: Purpose and Context - Business and technical objectives
  • Section 2: EARS in Development Workflow - SDD position and EARS role
  • Section 3: Requirements - Event-Driven, State-Driven, Unwanted Behavior, Ubiquitous
  • Section 4: Quality Attributes - Performance, Security, Reliability
  • Section 5: Traceability - Upstream sources, downstream artifacts, tags
  • Section 6: References - Internal and external documentation

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:

Type Pattern Example
Ubiquitous The [system] SHALL [action] The system SHALL log all errors
Event-Driven WHEN [trigger] THE [system] SHALL [action] WHEN user clicks submit THE system SHALL validate input
State-Driven WHILE [state] THE [system] SHALL [action] WHILE connected THE system SHALL maintain heartbeat
Unwanted IF [condition] THEN THE [system] SHALL [action] IF timeout occurs THEN THE system SHALL retry
Optional WHERE [feature] IS SUPPORTED THE [system] SHALL [action] WHERE dark mode IS SUPPORTED THE system SHALL apply theme
Complex Combination of patterns WHEN user logs in WHILE session active THE system SHALL refresh token

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

Code Severity Description
EARS-E001 error Missing required tag 'ears'
EARS-E002 error Missing required tag 'layer-3-artifact'
EARS-E003 error Invalid document_type
EARS-E004 error Invalid architecture_approaches format
EARS-E005 error Forbidden tag pattern detected
EARS-E006 error Missing required section
EARS-E007 error Multiple H1 headings detected
EARS-E008 error Section numbering not sequential
EARS-E009 error Document Control missing required fields
EARS-E010 error Invalid EARS pattern detected
EARS-E011 error Missing Traceability (Section 5)
EARS-E012 warning File name does not match format
EARS-W001 warning Requirement not using EARS syntax
EARS-W002 warning Missing upstream @brd or @prd tag
EARS-W003 warning BDD-Ready Score below 90%
EARS-W004 warning Requirement missing SHALL keyword
EARS-W005 warning Complex requirement too long
EARS-I001 info Consider adding unwanted behavior handling
EARS-I002 info Consider adding timing constraints (WITHIN)

Validation Commands

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

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

# Check with verbose output
python ai_dev_ssd_flow/03_EARS/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 (6-section MVP)
  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

Version Date Changes Author
1.3 2026-02-26 Migrated frontmatter to metadata; updated validator command paths to ai_dev_ssd_flow/03_EARS/scripts; aligned valid structure examples with audit-wrapper compatibility System
1.1 2026-02-11 Nested Folder Rule: Added Section 0 Folder Structure Validation (BLOCKING); EARS must be in docs/03_EARS/EARS-NN_{slug}/ folders; Added error codes EARS-E020, EARS-E021, EARS-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.
Weekly Installs
22
Repository
vladm3105/aidoc…ramework
GitHub Stars
9
First Seen
Feb 21, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
codex22
opencode21
gemini-cli21
github-copilot21
amp21
kimi-cli21