doc-sys

doc-sys

Purpose

Create System Requirements (SYS) documents - Layer 6 artifact in the SDD workflow that defines technical system requirements including functional capabilities and quality attributes.

Layer: 6

Upstream: BRD (Layer 1), PRD (Layer 2), EARS (Layer 3), BDD (Layer 4), ADR (Layer 5)

Downstream Artifacts: REQ (Layer 7), Code (Layer 13)

Prerequisites

Upstream Artifact Verification (CRITICAL)

Before creating this document, you MUST:

1. List existing upstream artifacts:

   ls docs/01_BRD/ docs/02_PRD/ docs/03_EARS/ docs/04_BDD/ docs/05_ADR/ docs/06_SYS/ docs/07_REQ/ 2>/dev/null
   

2. Reference only existing documents in traceability tags

3. Use null only when upstream artifact type genuinely doesn't exist

4. NEVER use placeholders like BRD-XXX or TBD

5. Do NOT create missing upstream artifacts - skip functionality instead

Before creating SYS, read:

1. Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md
2. Upstream ADR: Read architecture decisions constraining system
3. Template: ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md
4. Creation Rules: ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md
5. Validation Rules: ai_dev_ssd_flow/06_SYS/SYS_MVP_SCHEMA.yaml
6. Quality Gate Validation: ai_dev_ssd_flow/06_SYS/SYS_MVP_QUALITY_GATE_VALIDATION.md

When to Use This Skill

Use doc-sys when:

• Have completed BRD through ADR (Layers 1-5)
• Need to define system-level technical requirements
• Translating architecture decisions into requirements
• Specifying functional system behavior and quality attributes
• You are at Layer 6 of the SDD workflow

Reserved ID Exemption (SYS-00_*)

Scope: Documents with reserved ID 000 are FULLY EXEMPT from validation.

Pattern: SYS-00_*.md

Document Types: Index, Traceability matrix, Glossaries, Registries, Checklists

Validation Behavior: Skip all checks when filename matches SYS-00_* pattern.

SYS-Specific Guidance

1. SYS MVP Structure (15 Sections Total)

MVP Template: See ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md for complete 15-section structure.

Part 1 - System Definition:

• Document Control, Executive Summary, Scope

Part 2 - System Requirements:

• Functional Requirements, Quality Attributes

Part 3 - System Specification:

• Interface Specifications, Data Management Requirements, Testing and Validation Requirements

Part 4 - System Operations:

• Deployment and Operations Requirements, Compliance and Regulatory Requirements

Part 5 - Validation and Control:

• Acceptance Criteria, Risk Assessment, Traceability, Implementation Notes

2. Document Control Requirements

Required Fields (9 mandatory):

• Status, Version, Date Created/Last Updated, Author, Reviewers, Owner, Priority
• EARS-Ready Score
• REQ-Ready Score

Format:

| Item | Details |
|------|---------|
| **EARS-Ready Score** | ✅ 95% (Target: ≥90%) |
| **REQ-Ready Score** | ✅ 95% (Target: ≥90%) |

3. REQ-Ready Scoring System

Purpose: Measures SYS maturity and readiness for progression to Requirements (REQ) decomposition.

Format: ✅ NN% (Target: ≥90%)

Status and REQ-Ready Score Mapping:

REQ-Ready Score	Required Status
≥90%	Approved
70-89%	In Review
<70%	Draft

Scoring Criteria:

• Requirements Decomposition Clarity (35%): System boundaries, functional decomposition, dependencies, ADR alignment
• Quality Attributes Quantification (30%): Performance percentiles, reliability SLAs, security compliance, scalability metrics
• Interface Specifications (20%): External APIs (CTR-ready), internal interfaces, data exchange protocols
• Implementation Readiness (15%): Testing requirements, deployment/ops, monitoring/observability

Quality Gate: Score <90% blocks REQ artifact creation.

4. Element ID Format (MANDATORY)

Pattern: SYS.{DOC_NUM}.{HASH} (3 segments, dot-separated)

Element Type	Code	Example
Functional Requirement	01	SYS.02.0101
Quality Attribute	02	SYS.02.0201
Use Case	11	SYS.02.1101
System Requirement	26	SYS.02.2601

REMOVED PATTERNS - Do NOT use legacy formats:

• ❌ FR-XXX → Use SYS.NN.01.SS
• ❌ QA-XXX → Use SYS.NN.02.SS
• ❌ UC-XXX → Use SYS.NN.11.SS
• ❌ SR-XXX → Use SYS.NN.26.SS

Reference: ID_NAMING_STANDARDS.md

5. System Component Categorization

System Types:

• API Services: REST, GraphQL, or other API interfaces
• Data Processing: ETL, stream processing, batch processing systems
• Integration Services: Adapters, connectors, proxy services
• Supporting Services: Caching, messaging, configuration services
• Infrastructure Components: Load balancers, gateways, monitoring systems

Criticality Levels:

• Mission-Critical: Revenue-generating systems with <1 hour downtime SLA
• Business-Critical: Core operational systems with <4 hour downtime SLA
• Operational Support: Back-office systems with <24 hour downtime SLA

6. Threshold Registry Integration

Purpose: Prevent magic numbers by referencing centralized threshold registry.

@threshold Tag Format:

@threshold: PRD.NN.category.subcategory.key

SYS-Specific Threshold Categories:

Category	SYS Usage	Example Key
perf.*	Performance requirements	perf.api.p95_latency
sla.*	Uptime and availability targets	sla.uptime.target
timeout.*	Circuit breaker, connection timeouts	timeout.circuit_breaker.threshold
resource.*	Memory, CPU, storage limits	resource.memory.max_heap
limit.*	Rate limits, connection limits	limit.connection.max_total

Invalid (hardcoded values):

• ❌ p95 latency: 200ms
• ❌ uptime: 99.9%

Valid (registry references):

• ✅ p95 latency: @threshold: PRD.NN.perf.api.p95_latency
• ✅ uptime: @threshold: PRD.NN.sla.uptime.target

Tag Format Convention (By Design)

Notation	Format	Artifacts	Purpose
Dash	TYPE-NN	ADR, SPEC, CTR	Technical artifacts - references to files/documents
Dot	TYPE.NN.xxxx	BRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS	Hierarchical artifacts - references to elements inside documents

Key Distinction:

• @adr: ADR-033 → Points to the document ADR-033_risk_limit_enforcement.md
• @brd: BRD.17.0101 → Points to element 01.01 inside document BRD-017.md

Cumulative Tagging Requirements

Layer 6 (SYS): Must include tags from Layers 1-5 (BRD, PRD, EARS, BDD, ADR)

Tag Count: 5 tags (@brd, @prd, @ears, @bdd, @adr)

Format:

## Traceability

**Required Tags** (Cumulative Tagging Hierarchy - Layer 6):

@brd: BRD.01.0103
@prd: PRD.01.0702, PRD.01.0715
@ears: EARS.01.2501, EARS.01.2502
@bdd: BDD.01.1401
@adr: ADR-033, ADR-045

Upstream Sources:

• BRD-01
• PRD-01
• EARS-01 - EARS type code: 25
• BDD-01 - BDD scenario type code: 14
• ADR-033

Upstream/Downstream Artifacts

Upstream Sources:

• BRD (Layer 1) - Business requirements
• PRD (Layer 2) - Product features
• EARS (Layer 3) - Formal requirements
• BDD (Layer 4) - Test scenarios
• ADR (Layer 5) - Architecture decisions (CRITICAL - defines constraints)

Downstream Artifacts:

• REQ (Layer 7) - Atomic requirements decomposed from SYS
• Code (Layer 13) - Implementation of system requirements

Same-Type Document Relationships (conditional):

• @related-sys: SYS-NN - SYS documents sharing system context
• @depends-sys: SYS-NN - SYS that must be implemented first

Creation Process

Step 1: Read Upstream Artifacts

Especially focus on ADR (Layer 5) - architecture decisions constrain system requirements.

Step 2: Reserve ID Number

Check docs/06_SYS/ for next available ID number.

ID Numbering Convention: Start with 2 digits and expand only as needed.

• ✅ Correct: SYS-01, SYS-99, SYS-102
• ❌ Incorrect: SYS-001, SYS-009 (extra leading zero not required)

Step 3: Create SYS File

Nested Folder Rule (MANDATORY): ALL SYS documents MUST use nested folders regardless of document size.

Location: docs/06_SYS/SYS-NN_{slug}/SYS-NN_{slug}.md

Example: docs/06_SYS/SYS-01_order_management/SYS-01_order_management.md

CRITICAL: Never create SYS files directly in docs/06_SYS/ without a nested folder structure.

Step 4: Fill Document Control Section

Complete metadata including EARS-Ready Score and REQ-Ready Score.

Step 5: Define System Requirements

For each requirement:

• Use unified element ID format (SYS.NN.xxxx)
• Specify inputs, processing, outputs (for functional)
• Specify measurable criteria (for quality attributes)
• Use @threshold tags for all quantitative values
• Reference upstream EARS/PRD
• Link to BDD verification

Step 6: Create System Flows

Use Mermaid diagrams (not text-based):

• Sequence diagrams for interactions
• Flowcharts for logic
• State diagrams for workflows

Step 7: Document Technical Constraints

From ADR decisions:

• List each constraint
• Explain impact
• Define verification

Step 8: Add Cumulative Tags

Include all 5 upstream tags (@brd, @prd, @ears, @bdd, @adr).

Step 9: Create/Update Traceability Matrix

MANDATORY: Update traceability matrix (docs/06_SYS/SYS-00_TRACEABILITY_MATRIX.md)

Step 10: Validate SYS

Run validation commands (see Validation section).

Step 11: Commit Changes

Commit SYS file and traceability matrix.

Validation

Validation Checks (8 Total)

Check	Type	Description
CHECK 1	Error	Required Document Control Fields (9 fields)
CHECK 2	Error	ADR Compliance Validation
CHECK 3	Error	REQ-Ready Score Validation (format, threshold)
CHECK 4	Error	Quality Attribute Quantification
CHECK 5	Warning	System Boundaries
CHECK 6	Warning	Interface Specifications (CTR-ready)
CHECK 7	Warning	Upstream Traceability
CHECK 8	Error	Element ID Format Compliance (unified 3-segment)

Validation Tiers

Tier	Type	Exit Code	Action
Tier 1	Error	1	Must fix before commit
Tier 2	Warning	0	Recommended to fix
Tier 3	Info	0	No action required

Pre-Commit Hooks

SYS validation is automatically enforced via pre-commit hooks:

- id: sys-core-validator
  name: Validate SYS core checks (validator, framework library)
  entry: bash ai_dev_ssd_flow/06_SYS/scripts/sys_core_validator_hook.sh
  stages: [pre-commit]

- id: sys-quality-gate
  name: Validate SYS quality gates
  entry: bash ai_dev_ssd_flow/06_SYS/scripts/sys_quality_gate_hook.sh
  stages: [pre-commit]

- id: sys-req-ready-score
  name: Validate SYS REQ-Ready score (≥90%)
  entry: bash ai_dev_ssd_flow/06_SYS/scripts/sys_req_ready_score_hook.sh
  stages: [pre-commit]

Manual execution (for testing without committing):

pre-commit run sys-core-validator --all-files
pre-commit run sys-quality-gate --all-files
pre-commit run sys-req-ready-score --all-files

Quality Gates Enforced:

• ✅ SYS structure compliance (15 sections MVP)
• ✅ REQ-Ready score ≥90% for Approved status
• ✅ Metadata and tags (sys, layer-6-artifact)
• ✅ Upstream traceability (@brd, @prd, @ears, @bdd, @adr)
• ✅ Element ID format (SYS.NN.xxxx)
• ✅ No placeholder text in approved documents
• ✅ System diagrams (Mermaid required)
• ✅ Measurable requirements with @threshold tags
• ✅ Functional requirements and quality attributes coverage

Automated Validation

# Per-document validation (Phase 1)
python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/SYS-NN_{slug}/SYS-NN_{slug}.md --verbose

# Layer validation (Phase 2) - run when all SYS documents complete
python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/ --verbose

# Cumulative tagging validation
python ai_dev_ssd_flow/scripts/validate_tags_against_docs.py --artifact SYS-01 --expected-layers brd,prd,ears,bdd,adr --strict

Manual Checklist

• Document Control section with 9 required fields
• REQ-Ready Score with ✅ emoji and percentage
• Requirements use unified element ID format (SYS.NN.xxxx)
• No legacy patterns (FR-XXX, QA-XXX, UC-XXX, SR-XXX)
• Each requirement has measurable criteria
• All quantitative values use @threshold tags
• System flows use Mermaid diagrams
• Technical constraints from ADR documented
• Cumulative tags: @brd, @prd, @ears, @bdd, @adr included
• Each requirement references upstream source
• Verification method specified for each requirement
• Traceability matrix updated

Post-Creation Validation (MANDATORY - NO CONFIRMATION)

CRITICAL: Execute this validation loop IMMEDIATELY after document creation. Do NOT proceed to next document until validation passes.

Automatic Validation Loop

LOOP:
  1. Run: python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py {doc_path} --verbose
  2. IF errors fixed: GOTO LOOP (re-validate)
  3. IF warnings fixed: GOTO LOOP (re-validate)
  4. IF unfixable issues: Log for manual review, continue
  5. IF clean: Mark VALIDATED, proceed

Layer-Specific Upstream Requirements

This Layer	Required Upstream Tags	Count
SYS (Layer 6)	@brd, @prd, @ears, @bdd, @adr	5 tags

Auto-Fix Actions (No Confirmation Required)

Issue	Fix Action
Missing @brd/@prd/@ears/@bdd/@adr tag	Add with upstream document reference
Invalid tag format	Correct to TYPE.NN.xxxx (3-segment) or TYPE-NN format
Legacy element ID (FR-XXX, QA-XXX, etc.)	Convert to SYS.NN.xxxx format
Broken link	Recalculate path from current location
Missing traceability section	Insert from template

Validation Codes Reference

Code	Description	Severity
XDOC-001	Referenced requirement ID not found	ERROR
XDOC-002	Missing cumulative tag	ERROR
XDOC-003	Upstream document not found	ERROR
XDOC-006	Tag format invalid	ERROR
XDOC-007	Gap in cumulative tag chain	ERROR
XDOC-009	Missing traceability section	ERROR

Quality Gate

Blocking: YES - Cannot proceed to REQ creation until Phase 1 validation passes with 0 errors.

Common Pitfalls

1. Vague requirements: Must be measurable (not "fast" but "P95 <50ms")
2. Missing ADR constraints: System requirements must respect ADR decisions
3. Text-based diagrams: Use Mermaid ONLY, not ASCII art or code blocks
4. Missing cumulative tags: Layer 6 must include all 5 upstream tags
5. No verification method: Each requirement needs test approach
6. Legacy element IDs: Use SYS.NN.xxxx not FR-XXX/QA-XXX/SR-XXX
7. Hardcoded values: Use @threshold tags, not magic numbers
8. Wrong REQ-Ready Score format: Must include ✅ emoji and percentage

---

Downstream Creation Guidelines

Creating REQ from SYS

REQ Decomposition Rules:

1. Each SYS functional requirement → 3-7 atomic REQ files
2. Each SYS quality attribute category → 2-4 atomic REQ files per category
3. Each SYS interface → 1-3 atomic REQ files per interface

REQ Validation Against SYS:

• All REQ capabilities must fit within SYS system boundaries
• All REQ acceptance criteria must satisfy SYS exit criteria
• All REQ quality attribute targets must meet or exceed SYS thresholds

Interface CTR Creation:

• When SYS specifies external API contracts, create CTR documents
• CTR requirements must exactly match SYS interface specifications

---

Next Skill

After creating SYS, use:

doc-req - Create Atomic Requirements (Layer 7)

The REQ will:

• Decompose SYS into atomic requirements
• Include all 6 upstream tags (@brd through @sys)
• Use REQ v3.0 format (12 sections)
• Achieve ≥90% SPEC-readiness

Reference Documents

SYS artifacts do not support REF documents. Reference documents are limited to BRD and ADR types only per the SDD framework.

For supplementary documentation needs, create:

• BRD-REF: Business context documentation
• ADR-REF: System architecture guides, QA attribute catalogs

Related Resources

• Template: ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md (primary authority)
• SYS Creation Rules: ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md
• SYS Validation Rules: ai_dev_ssd_flow/06_SYS/SYS_MVP_SCHEMA.yaml
• SYS README: ai_dev_ssd_flow/06_SYS/README.md
• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

Sectioning Guidance (for documents >25K tokens):

• Follow split rules in ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md
• Reference: ai_dev_ssd_flow/ID_NAMING_STANDARDS.md (Section-Based File Splitting)

Quick Reference

SYS Purpose: Define system-level technical requirements

Layer: 6

Tags Required: @brd, @prd, @ears, @bdd, @adr (5 tags)

REQ-Ready Score: ≥90% required for "Approved" status

Element ID Format: SYS.NN.xxxx (FR=01, QA=02, UC=11, SR=26)

Key Sections:

• System Requirements (unified element IDs)
• System Flows (Mermaid diagrams)
• Technical Constraints (from ADR)

Critical: Use @threshold tags for all quantitative values

Next: doc-req

---

Version History

Version	Date	Changes	Author
1.2	2026-03-06	Added quality gate validation reference and pre-commit hooks section	System
1.1	2026-02-27	Migrated frontmatter to metadata; normalized SYS canonical references to ai_dev_ssd_flow; removed non-existent section-template references; aligned validation commands to validate_sys.py	System
1.0	2026-02-08	Initial skill definition with YAML frontmatter standardization	System