name	doc-sys: Create System Requirements (Layer 6)
description	Create System Requirements (SYS) - Layer 6 artifact defining functional requirements and quality attributes
tags	sdd-workflow, layer-6-artifact, shared-architecture
custom_fields	[object Object]

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:

List existing upstream artifacts:

ls docs/BRD/ docs/PRD/ docs/EARS/ docs/BDD/ docs/ADR/ docs/SYS/ docs/REQ/ 2>/dev/null

Reference only existing documents in traceability tags
Use null only when upstream artifact type genuinely doesn't exist
NEVER use placeholders like BRD-XXX or TBD
Do NOT create missing upstream artifacts - skip functionality instead

Before creating SYS, read:

Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md
Upstream ADR: Read architecture decisions constraining system
Template: ai_dev_flow/SYS/SYS-TEMPLATE.md
Creation Rules: ai_dev_flow/SYS/SYS_CREATION_RULES.md
Validation Rules: ai_dev_flow/SYS/SYS_VALIDATION_RULES.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-000_*)

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

Pattern: SYS-000_*.md

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

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

SYS-Specific Guidance

1. Five-Part SYS Document Structure

Full Template: See ai_dev_flow/SYS/SYS-TEMPLATE.md for complete 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}.{ELEM_TYPE}.{SEQ} (4 segments, dot-separated)

Element Type	Code	Example
Functional Requirement	01	SYS.02.01.01
Quality Attribute	02	SYS.02.02.01
Use Case	11	SYS.02.11.01
System Requirement	26	SYS.02.26.01

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, IPLAN, ICON	Technical artifacts - references to files/documents
Dot	TYPE.NN.TT.SS	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.01.01 → 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.01.03
@prd: PRD.01.07.02, PRD.01.07.15
@ears: EARS.01.25.01, EARS.01.25.02
@bdd: BDD.01.14.01
@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 ai_dev_flow/SYS/ for next available ID number.

Step 3: Create SYS File

Location: docs/SYS/SYS-NN_{slug}.md (template at ai_dev_flow/SYS/)

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

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.TT.SS)
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 (ai_dev_flow/SYS/SYS-000_TRACEABILITY_MATRIX-TEMPLATE.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 4-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

Automated Validation

# Per-document validation (Phase 1)
python ai_dev_flow/scripts/validate_cross_document.py --document docs/SYS/SYS-NN_slug.md --auto-fix

# Layer validation (Phase 2) - run when all SYS documents complete
python ai_dev_flow/scripts/validate_cross_document.py --layer SYS --auto-fix

# Cumulative tagging validation
python ai_dev_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.TT.SS)
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_flow/scripts/validate_cross_document.py --document {doc_path} --auto-fix
  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.TT.SS (4-segment) or TYPE-NN format
Legacy element ID (FR-XXX, QA-XXX, etc.)	Convert to SYS.NN.TT.SS 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

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

Downstream Creation Guidelines

Creating REQ from SYS

REQ Decomposition Rules:

Each SYS functional requirement → 3-7 atomic REQ files
Each SYS quality attribute category → 2-4 atomic REQ files per category
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_flow/SYS/SYS-TEMPLATE.md (primary authority)
SYS Creation Rules: ai_dev_flow/SYS/SYS_CREATION_RULES.md
SYS Validation Rules: ai_dev_flow/SYS/SYS_VALIDATION_RULES.md
SYS README: ai_dev_flow/SYS/README.md
Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

Section Templates (for documents >25K tokens):

Index template: ai_dev_flow/SYS/SYS-SECTION-0-TEMPLATE.md
Content template: ai_dev_flow/SYS/SYS-SECTION-TEMPLATE.md
Reference: ai_dev_flow/ID_NAMING_STANDARDS.md (Section-Based File Splitting)

Quick Reference

SYS Purpose: Define system-level technical requirements