name	doc-req-validator
description	Validate Atomic Requirements (REQ) documents against Layer 7 schema standards
metadata	{"tags":["sdd-workflow","layer-7-artifact","quality-assurance"],"custom_fields":{"layer":7,"artifact_type":"REQ","architecture_approaches":["ai-agent-based","traditional-8layer"],"priority":"shared","development_status":"active","skill_category":"quality-assurance","upstream_artifacts":["REQ"],"downstream_artifacts":[],"version":"1.2","last_updated":"2026-02-27"},"versioning_policy":"tracks REQ_MVP_SCHEMA schema_version"}

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.

name	doc-req-validator
description	Validate Atomic Requirements (REQ) documents against Layer 7 schema standards
metadata	{"tags":["sdd-workflow","layer-7-artifact","quality-assurance"],"custom_fields":{"layer":7,"artifact_type":"REQ","architecture_approaches":["ai-agent-based","traditional-8layer"],"priority":"shared","development_status":"active","skill_category":"quality-assurance","upstream_artifacts":["REQ"],"downstream_artifacts":[],"version":"1.2","last_updated":"2026-02-27"},"versioning_policy":"tracks REQ_MVP_SCHEMA schema_version"}