doc-req-validator

Validate Atomic Requirements (REQ) documents against Layer 7 schema standards.

Activation

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

Validation Schema Reference

Schema: ai_dev_ssd_flow/07_REQ/REQ_MVP_SCHEMA.yaml

Layer: 7 Artifact Type: REQ

Validation Checklist

0. Folder Structure Validation (BLOCKING)

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

Required Structure:

REQ Type Required Location

Monolithic docs/07_REQ/REQ-NN_{slug}/REQ-NN_{slug}.md

Validation:

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

Example Valid Structure:

docs/07_REQ/ ├── REQ-01_f1_iam/ │ ├── REQ-01_f1_iam.md ✓ Valid │ ├── REQ-01.R_review_report_v001.md │ └── .drift_cache.json ├── REQ-02_f2_session/ │ └── REQ-02_f2_session.md ✓ Valid

Invalid Structure:

docs/07_REQ/ ├── REQ-01_f1_iam.md ✗ NOT in nested folder

Error Codes:

Code Severity Description

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

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

REQ-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 - REQ must pass folder structure validation before other checks proceed.

1. Metadata Validation

Required custom_fields:

• document_type: ["req", "template"]
• artifact_type: "REQ"
• layer: 7
• architecture_approaches: [array format]
• priority: ["primary", "shared", "fallback"]
• development_status: ["active", "draft", "deprecated", "reference"]

Required tags:

• req (or req-template)
• layer-7-artifact

Forbidden tag patterns:

• "^req-document$"
• "^requirements$"
• "^atomic-requirements$"
• "^req-\d{3}$"

2. Structure Validation

Required Sections (11 sections - MVP):

• Title (H1): # REQ-NN: [RESOURCE_TYPE] Title

• Section 1: Document Control

• Section 2: Requirement Description

• Section 3: Functional Specification

• Section 4: Interface Definition

• Section 5: Error Handling

• Section 6: Quality Attributes

• Section 7: Configuration

• Section 8: Testing Requirements

• Section 9: Acceptance Criteria (≥3 measurable criteria)

• Section 10: Traceability

• Section 11: Implementation Notes

Note: MVP template intentionally omits Change History to maintain 11-section structure.

Document Control Required Fields:

• Status

• Version

• Date Created

• Last Updated

• Author

• Priority

• Category

• Source Document

• Verification Method

• Assigned Team

• SPEC-Ready Score

File Naming: Pattern: REQ-NNN_descriptive_name.md

3. Content Validation

Requirement Keywords:

• SHALL: Mandatory requirement

• SHOULD: Recommended requirement

• MAY: Optional requirement

Acceptance Criteria Format:

• Pattern: AC-NNN

• Minimum count: 15 criteria

• Categories: Primary Functional (5), Error/Edge Case (5), Quality/Constraint (3), Data Validation (2), Integration (3)

Interface Specifications:

• Protocol/ABC definition with type hints

• DTO definitions (dataclass or Pydantic)

• REST endpoints (optional)

Data Schema Patterns:

• JSON Schema (draft-07)

• Pydantic BaseModel with validators

• Database schema (optional)

SPEC-Ready Score:

• Minimum threshold: 90%

• Components: Interface completeness, data schema, error handling, configuration, quality attributes, implementation guidance, acceptance criteria, traceability

4. Traceability Validation

Layer 7 Cumulative Tags:

• @brd: BRD.NN.EE.SS (required)

• @prd: PRD.NN.EE.SS (required)

• @ears: EARS.NN.EE.SS (required)

• @bdd: BDD.NN.EE.SS (required)

• @adr: ADR-NN (required)

• @sys: SYS.NN.EE.SS (required)

Downstream Expected:

• IMPL documents

• CTR documents

• SPEC documents

• TASKS documents

Same-Type References:

• @related-req: REQ-NN

• @depends-req: REQ-NN

Error Codes

Code Severity Description

REQ-E001 error Missing required tag 'req'

REQ-E002 error Missing required tag 'layer-7-artifact'

REQ-E003 error Invalid document_type

REQ-E004 error Invalid architecture_approaches format

REQ-E005 error Forbidden tag pattern detected

REQ-E006 error Missing required section

REQ-E007 error Multiple H1 headings detected

REQ-E008 error Section numbering not sequential (1-11)

REQ-E009 error Document Control missing required fields

REQ-E010 error Missing Interface Specifications (Section 3)

REQ-E011 error Missing Data Schemas (Section 4)

REQ-E012 error Missing Error Handling (Section 5)

REQ-E013 error Missing Acceptance Criteria (Section 9)

REQ-E014 warning File name does not match format

REQ-E015 error Missing Protocol/ABC definition

REQ-E016 error Missing JSON Schema or Pydantic models

REQ-E017 error Missing Exception Catalog

REQ-W001 warning SPEC-Ready Score below 90%

REQ-W002 warning Acceptance Criteria count below 15

REQ-W003 warning Missing upstream tags (require 6)

REQ-W004 warning Missing Description Context subsections

REQ-W005 warning Missing Performance targets (p50/p95/p99)

REQ-W006 warning Missing Implementation Guidance patterns

REQ-W007 warning Code paths appear to be placeholders

REQ-I001 info Consider adding database schema

REQ-I002 info Consider adding REST endpoints

REQ-I003 info Python code should include type hints

Validation Commands

Validate single REQ document

./ai_dev_ssd_flow/07_REQ/scripts/validate_req_template.sh docs/07_REQ/REQ-001_example/REQ-001_example.md

Validate all REQ documents

find docs/07_REQ -name "REQ-*.md" -exec ./ai_dev_ssd_flow/07_REQ/scripts/validate_req_template.sh {} ;

Check with verbose output

python3 ai_dev_ssd_flow/07_REQ/scripts/validate_req_spec_readiness.py docs/07_REQ/REQ-001_example/REQ-001_example.md --verbose

Validation Workflow

• Parse YAML frontmatter

• Check required metadata fields

• Validate tag taxonomy

• Verify section structure (1-11)

• Validate Document Control table

• Check Interface Specifications (Protocol/ABC)

• Check Data Schemas (JSON/Pydantic)

• Check Error Handling (Exception Catalog)

• Verify Acceptance Criteria count (≥15)

• Validate upstream references (6 required)

• Calculate SPEC-Ready Score

• Verify file naming convention

• Generate validation report

Integration

• Invoked by: doc-flow, doc-req (post-creation)

• Feeds into: trace-check (cross-document validation)

• Reports to: quality-advisor

Output Format

REQ Validation Report

Document: REQ-001_example.md Status: PASS/FAIL

Interface Coverage:

• Protocol/ABC: Present/Missing
• DTOs: Present/Missing
• REST Endpoints: Present/Missing

Data Schema Coverage:

• JSON Schema: Present/Missing
• Pydantic Models: Present/Missing
• Database Schema: Present/Missing

Acceptance Criteria: N/15

Errors: N Warnings: N Info: N

[Details listed by severity]

Version History

Version Date Changes Author

1.1 2026-02-11 Nested Folder Rule: Added Section 0 Folder Structure Validation (BLOCKING); REQ must be in docs/07_REQ/REQ-NN_{slug}/ folders; Added error codes REQ-E020, REQ-E021, REQ-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 .