// Validate System Requirements (SYS) documents against Layer 6 schema standards
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | doc-sys-validator |
| description | Validate System Requirements (SYS) documents against Layer 6 schema standards |
| metadata | {"tags":["sdd-workflow","layer-6-artifact","quality-assurance"],"custom_fields":{"layer":6,"artifact_type":"SYS","architecture_approaches":["ai-agent-based","traditional-8layer"],"priority":"shared","development_status":"active","skill_category":"quality-assurance","upstream_artifacts":["SYS"],"downstream_artifacts":[],"version":"1.2","last_updated":"2026-02-27"},"versioning_policy":"tracks SYS-MVP_SCHEMA schema_version"} |
Validate System Requirements (SYS) documents against Layer 6 schema standards.
Invoke when user requests validation of SYS documents or after creating/modifying SYS artifacts.
Schema: ai_dev_ssd_flow/06_SYS/SYS_MVP_SCHEMA.yaml
Layer: 6
Artifact Type: SYS
Nested Folder Rule: ALL SYS documents MUST be in nested folders regardless of size.
Required Structure:
| SYS Type | Required Location |
|---|---|
| Monolithic | docs/06_SYS/SYS-NN_{slug}/SYS-NN_{slug}.md |
Validation:
1. Check document is inside a nested folder: docs/06_SYS/SYS-NN_{slug}/
2. Verify folder name matches SYS ID pattern: SYS-NN_{slug}
3. Verify file name matches folder: SYS-NN_{slug}.md
4. Parent path must be: docs/06_SYS/
Example Valid Structure:
docs/06_SYS/
āāā SYS-01_f1_iam/
ā āāā SYS-01_f1_iam.md ā Valid
ā āāā SYS-01.R_review_report_v001.md
ā āāā .drift_cache.json
āāā SYS-02_f2_session/
ā āāā SYS-02_f2_session.md ā Valid
Invalid Structure:
docs/06_SYS/
āāā SYS-01_f1_iam.md ā NOT in nested folder
Error Codes:
| Code | Severity | Description |
|---|---|---|
| SYS-E020 | ERROR | SYS not in nested folder (BLOCKING) |
| SYS-E021 | ERROR | Folder name doesn't match SYS ID |
| SYS-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 - SYS must pass folder structure validation before other checks proceed.
Required custom_fields:
- document_type: ["sys", "template"]
- artifact_type: "SYS"
- layer: 6
- architecture_approaches: [array format]
- priority: ["primary", "shared", "fallback"]
- development_status: ["active", "draft", "deprecated", "reference"]
Required tags:
- sys (or sys-template)
- layer-6-artifact
Forbidden tag patterns:
- "^system-requirements$"
- "^sys-doc$"
- "^sys-\\d{3}$"
Required Sections (15 sections):
# SYS-NNN: TitleDocument Control Required Fields:
File Naming:
Pattern: SYS-NNN_descriptive_name.md
Functional Requirement Format:
SYS.NN.01.SS (unified 3-segment format)Quality Attribute Format (3-segment):
SYS.NN.02.SS (02 = Quality Attribute type)SYS.08.0215Quality Attribute Metrics:
| Category | Keywords | Metrics |
|---|---|---|
| Performance | latency, response time, throughput, p50/p95/p99 | Response Time, Throughput, Latency |
| Reliability | uptime, availability, MTBF, MTTR | Availability, Error Rate |
| Scalability | concurrent, horizontal, vertical | Concurrent Users, Data Volume |
| Security | auth, encrypt, RBAC, compliance | Authentication, Authorization |
| Observability | log, monitor, alert, trace | Logging, Monitoring, Alerting |
| Maintainability | coverage, deploy, CI/CD | Code Coverage, Deploy Frequency |
REQ-Ready Score:
Layer 6 Cumulative Tags:
Downstream Expected:
Same-Type References:
| Code | Severity | Description |
|---|---|---|
| SYS-E001 | error | Missing required tag 'sys' |
| SYS-E002 | error | Missing required tag 'layer-6-artifact' |
| SYS-E003 | error | Invalid document_type |
| SYS-E004 | error | Invalid architecture_approaches format |
| SYS-E005 | error | Forbidden tag pattern detected |
| SYS-E006 | error | Missing required section |
| SYS-E007 | error | Multiple H1 headings detected |
| SYS-E008 | error | Section numbering not sequential (1-15) |
| SYS-E009 | error | Document Control missing required fields |
| SYS-E010 | error | Missing Functional Requirements (Section 4) |
| SYS-E011 | error | Missing Quality Attributes (Section 5) |
| SYS-E012 | error | Missing Traceability (Section 13) |
| SYS-E013 | warning | File name does not match format |
| SYS-W001 | warning | Functional requirements not using SYS.NN.01.SS |
| SYS-W002 | warning | Quality attributes not using 3-segment format |
| SYS-W003 | warning | Missing Performance category |
| SYS-W004 | warning | Missing Security category |
| SYS-W005 | warning | Missing upstream tags (require 5) |
| SYS-W006 | warning | REQ-Ready Score below 90% |
| SYS-W007 | warning | Testing Requirements missing coverage |
| SYS-I001 | info | Consider adding p50/p95/p99 latency |
| SYS-I002 | info | Consider adding MTBF/MTTR metrics |
# Validate single SYS document
python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/SYS-01_example/SYS-01_example.md
# Validate all SYS documents
python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/
# Check with verbose output
python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/ --verbose
SYS Validation Report
=====================
Document: SYS-001_example.md
Status: PASS/FAIL
Quality Attribute Coverage:
- Performance: Present/Missing
- Reliability: Present/Missing
- Security: Present/Missing
- Scalability: Present/Missing
- Observability: Present/Missing
Errors: N
Warnings: N
Info: N
[Details listed by severity]
| Version | Date | Changes | Author |
|---|---|---|---|
| 1.2 | 2026-02-27 | Migrated frontmatter to metadata; aligned schema to SYS_MVP_SCHEMA.yaml; normalized validation commands to ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py | System |
| 1.1 | 2026-02-11 | Nested Folder Rule: Added Section 0 Folder Structure Validation (BLOCKING); SYS must be in docs/06_SYS/SYS-NN_{slug}/ folders; Added error codes SYS-E020, SYS-E021, SYS-E022 | |
| 1.0 | 2026-02-08 | Initial validator skill definition with YAML frontmatter | System |
--iplan > --ref > --prompt.docs-v2.0/00_REF.