name: doc-req
description: Create Atomic Requirements (REQ) - Layer 7 artifact using REQ v3.0 format with 12 sections, SPEC-readiness scoring, and IMPL-readiness scoring
tags:
- sdd-workflow
- layer-7-artifact
- shared-architecture
custom_fields:
layer: 7
artifact_type: REQ
architecture_approaches: [ai-agent-based, traditional-8layer]
priority: shared
development_status: active
skill_category: core-workflow
upstream_artifacts: [BRD,PRD,EARS,BDD,ADR,SYS]
downstream_artifacts: [IMPL,CTR,SPEC]

doc-req

Purpose

Create Atomic Requirements (REQ) documents - Layer 7 artifact in the SDD workflow that decomposes system requirements into atomic, implementation-ready requirements using REQ v3.0 format.

Layer: 7

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

Downstream Artifacts: IMPL (Layer 8), CTR (Layer 9), SPEC (Layer 10), Code (Layer 13)

Prerequisites

Upstream Artifact Verification (CRITICAL)

Before creating this document, you MUST:

1. List existing upstream artifacts:
   bash ls docs/BRD/ docs/PRD/ docs/EARS/ docs/BDD/ docs/ADR/ docs/SYS/ docs/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 REQ, read:

1. Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md
2. Upstream SYS: Read system requirements driving this REQ
3. Template: ai_dev_flow/REQ/REQ-TEMPLATE.md
4. Creation Rules: ai_dev_flow/REQ/REQ_CREATION_RULES.md
5. Validation Rules: ai_dev_flow/REQ/REQ_VALIDATION_RULES.md
6. Validation Script: ./ai_dev_flow/scripts/validate_req_template.sh

When to Use This Skill

Use doc-req when:
- Have completed BRD through SYS (Layers 1-6)
- Need to decompose system requirements into atomic units
- Preparing for implementation (Layer 8+)
- Achieving >=90% SPEC-readiness score
- You are at Layer 7 of the SDD workflow

Reserved ID Exemption (REQ-00_*)

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

Pattern: REQ-00_*.md

Document Types:
- Index documents (REQ-00_index.md)
- Traceability matrix templates (REQ-00_TRACEABILITY_MATRIX-TEMPLATE.md)
- Glossaries, registries, checklists

Rationale: Reserved ID 000 documents are framework infrastructure, not project artifacts requiring traceability or quality gates.

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

REQ-Specific Guidance

1. REQ v3.0 Format (12 Required Sections)

CRITICAL: REQ v3.0 expanded from 7 to 12 sections

Document Control (MANDATORY - First section before all numbered sections)

Core Sections:
1. Description: Atomic requirement + SHALL/SHOULD/MAY language + context + scenario
2. Functional Requirements: Core capabilities + business rules
3. Interface Specifications: Protocol/ABC definitions + DTOs + REST endpoints
4. Data Schemas: JSON Schema + Pydantic models + Database schema
5. Error Handling Specifications: Exception catalog + error response schema + circuit breaker config
6. Configuration Specifications: YAML schema + environment variables + validation
7. Quality Attributes: Performance targets (p50/p95/p99) + reliability/security/scalability
8. Implementation Guidance: Algorithms/patterns + concurrency/async + dependency injection
9. Acceptance Criteria: >=15 measurable criteria covering functional/error/quality/data/integration
10. Verification Methods: BDD scenarios + unit/integration/contract/performance tests
11. Traceability: Section 7 format with cumulative tags (6 required)
12. Change History: Version control table

2. Document Control Requirements (11 Mandatory Fields)

3. Dual Readiness Scoring (SPEC-Ready + IMPL-Ready)

MANDATORY: Each REQ must calculate BOTH scores

SPEC-Ready Score Formula:

SPEC-Ready Score = (Completed Sections / 12) * 100%

IMPL-Ready Score: Measures readiness for implementation approach documentation

Quality Gate: Both scores >=90% required for layer transition

Status and Ready Score Mapping:

Note: For REQ documents with dual scores, use the LOWER score to determine status.

Example:

## Readiness Scores

**SPEC-Ready Score**: >=95% (Target: >=90%)
**IMPL-Ready Score**: >=92% (Target: >=90%)

**Section Status**:
- [x] 1. Description
- [x] 2. Functional Requirements
- [x] 3. Interface Specifications
- [x] 4. Data Schemas
- [x] 5. Error Handling Specifications
- [x] 6. Configuration Specifications
- [x] 7. Quality Attributes
- [x] 8. Implementation Guidance
- [x] 9. Acceptance Criteria
- [x] 10. Verification Methods
- [x] 11. Traceability
- [ ] 12. Change History (In Progress)

**Readiness**: READY for SPEC/IMPL creation

4. Element ID Format (MANDATORY)

Pattern: REQ.{DOC_NUM}.{ELEM_TYPE}.{SEQ} (4 segments, dot-separated)

REMOVED PATTERNS - Do NOT use:
- AC-XXX - Use REQ.NN.06.SS
- FR-XXX - Use REQ.NN.01.SS
- R-XXX - Use REQ.NN.27.SS
- REQ-XXX - Use REQ.NN.27.SS

Reference: ID_NAMING_STANDARDS.md - Cross-Reference Link Format

5. Atomic Requirement Principles

• Single Responsibility: Each REQ defines exactly one requirement
• Measurable: Acceptance criteria provide true/false outcomes
• Self-Contained: Understandable without external context
• SPEC-Ready: Contains ALL information for automated SPEC generation (>=90% completeness)
• Modal Language: SHALL (absolute), SHOULD (preferred), MAY (optional)

6. Domain/Subdomain Organization

Location: REQ/{domain}/{subdomain}/ within project docs directory

Domains: api/ (external integrations), risk/ (risk management), data/ (data requirements), ml/ (ML requirements), auth/ (security), etc.

Format: REQ-NN_descriptive_slug.md

Example: REQ-risk-limits-01_position_validation.md

Tag Format Convention (By Design)

The SDD framework uses two distinct notation systems for cross-references:

Key Distinction:
- @adr: ADR-033 -> Points to the document ADR-033_risk_limit_enforcement.md
- @brd: BRD.17.01.03 -> Points to element 01.03 inside document BRD-017.md

Cumulative Tagging Requirements

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

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

Format:

## Traceability

**Required Tags** (Cumulative Tagging Hierarchy - Layer 7):
```markdown
@brd: BRD.01.01.03
@prd: PRD.01.07.02
@ears: EARS.01.25.01
@bdd: BDD.01.14.01
@adr: ADR-033, ADR-045
@sys: SYS.01.01.01, SYS.01.02.07

Upstream Sources:
- BRD-01
- PRD-01
- EARS-01
- BDD-01
- ADR-033
- SYS-01

Downstream Artifacts:
- IMPL-NN (to be created) - Implementation approach
- CTR-NN (to be created) - Data contracts
- SPEC-NN (to be created) - Technical specifications

**Element Type Codes for Tags**:
- EARS: Type 25 (formal requirement)
- BDD: Type 14 (scenario)
- SYS: Type 01 (functional), 02 (quality attribute), 26 (system req)

## Threshold Registry Integration

**Purpose**: Prevent magic numbers by referencing centralized threshold registry.

### When @threshold Tag is Required

Use `@threshold` for ALL quantitative values that are:
- Business-critical (compliance limits, SLAs)
- Configurable (timeout values, rate limits, retry policies)
- Shared across documents (performance targets)
- Quality attribute-related (p50/p95/p99 latencies, throughput limits)
- Error handling configurations (circuit breaker, retry counts)

### @threshold Tag Format

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

Examples:
- @threshold: PRD.035.perf.api.p95_latency
- @threshold: PRD.035.timeout.circuit_breaker.threshold
- @threshold: PRD.035.retry.max_attempts
- @threshold: PRD.035.limit.api.requests_per_second

REQ-Specific Threshold Categories

Magic Number Detection

Invalid (hardcoded values):
- p95 response time: 200ms
- max_retries: 3
- rate_limit: 100 req/s

Valid (registry references):
- p95 response time: @threshold: PRD.NN.perf.api.p95_latency
- max_retries: @threshold: PRD.NN.retry.max_attempts
- rate_limit: @threshold: PRD.NN.limit.api.requests_per_second

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
- SYS (Layer 6) - System requirements (PRIMARY SOURCE)

Downstream Artifacts:
- IMPL (Layer 8) - Implementation approach (optional)
- CTR (Layer 9) - Data contracts (optional)
- SPEC (Layer 10) - Technical specifications
- Code (Layer 13) - Implementation

Same-Type Document Relationships (conditional):
- @related-req: REQ-NN - REQs sharing domain context
- @depends-req: REQ-NN - REQ that must be implemented first

Creation Process

Step 1: Read Upstream Artifacts

Especially focus on SYS (Layer 6) - system requirements to decompose.

Step 2: Reserve ID Number

Check ai_dev_flow/REQ/ for next available ID number.

ID Numbering Convention: Start with 2 digits and expand only as needed.
- ✅ Correct: REQ-01, REQ-99, REQ-102
- ❌ Incorrect: REQ-001, REQ-009 (extra leading zero not required)

Domain-based naming: REQ-domain-subdomain-NN

Step 3: Create REQ File

Location Options:
- Flat: docs/REQ/REQ-{NN}_{slug}.md
- Domain-based: docs/REQ/{domain}/REQ-NN_{slug}.md
- Subdomain: docs/REQ/{domain}/{subdomain}/REQ-NN_{slug}.md

On-Demand Folder Creation: Before saving the document, create the target directory:

# Create target directory if it doesn't exist
mkdir -p docs/REQ/{domain}/         # For domain-based structure
# OR
mkdir -p docs/REQ/{domain}/{subdomain}/  # For subdomain structure

Domain Selection: Use domain from project configuration or upstream SYS context:
- Financial: risk/, trading/, collection/, compliance/, ml/
- SaaS: tenant/, subscription/, billing/, workspace/
- Generic: api/, auth/, data/, core/, integration/

Section Files: For large requirements (>50KB), use Section Files format: REQ-NN.S_section_title.md (S = section number).

Step 4: Fill Document Control Section

Complete metadata with all 11 required fields plus Document Revision History table.

Step 5: Complete All 12 Required Sections

Critical: REQ v3.0 requires all 12 sections for >=90% SPEC-readiness

1. Description: Atomic requirement + SHALL/SHOULD/MAY language
2. Functional Requirements: Core capabilities + business rules
3. Interface Specifications: APIs, endpoints, contracts, Protocol/ABC class
4. Data Schemas: Models, validation, constraints, Pydantic/dataclass
5. Error Handling Specifications: Error codes, recovery, exception definitions
6. Configuration Specifications: Settings, feature flags, YAML config
7. Quality Attributes: Performance, security, scalability with thresholds
8. Implementation Guidance: Technical approach, patterns
9. Acceptance Criteria: >=15 measurable criteria
10. Verification Methods: BDD scenarios, tests
11. Traceability: Cumulative tags (6 tags)
12. Change History: Version control table

Step 6: Calculate Readiness Scores

Count completed sections and calculate both SPEC-Ready and IMPL-Ready percentages.

Quality Gate: Both scores must achieve >=90%

Step 7: Add Cumulative Tags

Include all 6 upstream tags (@brd through @sys).

Step 8: Create/Update Traceability Matrix

MANDATORY: Update ai_dev_flow/REQ/REQ-00_TRACEABILITY_MATRIX-TEMPLATE.md

Step 9: Validate REQ

./ai_dev_flow/scripts/validate_req_template.sh ai_dev_flow/REQ/REQ-NN_*.md

python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact REQ-NN --expected-layers brd,prd,ears,bdd,adr,sys --strict

Step 10: Commit Changes

Commit REQ file and traceability matrix.

Validation

Validation Checks (20 Total)

Validation Tiers

Automated Validation

# Validate single file
./scripts/validate_req_template.sh docs/REQ/REQ-NN_slug.md

# Validate all REQ files
find docs/REQ -name "REQ-*.md" -exec ./scripts/validate_req_template.sh {} \;

# Cumulative tagging validation
python ai_dev_flow/scripts/validate_tags_against_docs.py \
  --artifact REQ-NN \
  --expected-layers brd,prd,ears,bdd,adr,sys \
  --strict

Manual Checklist

• [ ] Document Control section at top with 11 required fields
• [ ] All 12 required sections completed
• [ ] SPEC-Ready Score >=90%
• [ ] IMPL-Ready Score >=90%
• [ ] Template Version = 3.0
• [ ] Section 3: Interface Specifications with Protocol/ABC class
• [ ] Section 4: Data Schemas with Pydantic/dataclass models
• [ ] Section 5: Error Handling with exception definitions
• [ ] Section 6: Configuration with YAML schema
• [ ] Section 7: Quality Attributes with @threshold references
• [ ] Section 9: >=15 acceptance criteria
• [ ] Cumulative tags: @brd through @sys (6 tags) included
• [ ] Each requirement atomic (single responsibility)
• [ ] Acceptance criteria testable and measurable
• [ ] Traceability matrix updated

Diagram Standards

All diagrams MUST use Mermaid syntax. Text-based diagrams (ASCII art, box drawings) are prohibited.
See: ai_dev_flow/DIAGRAM_STANDARDS.md and mermaid-gen skill.

Common Pitfalls

1. Incomplete sections: All 12 sections mandatory for SPEC-readiness
2. Missing new sections: Sections 3-7 are new in v3.0 - don't skip them
3. Low readiness scores: Both SPEC-Ready and IMPL-Ready must achieve >=90%
4. Non-atomic requirements: Each REQ must be single, testable unit
5. Missing cumulative tags: Layer 7 must include all 6 upstream tags
6. Vague acceptance criteria: Must be measurable and testable
7. Hardcoded values: Use @threshold references, not magic numbers
8. Legacy element IDs: Use REQ.NN.TT.SS format, not AC-XXX or FR-XXX
9. Status/score mismatch: Status must match the LOWER of the two scores

Post-Creation Validation (MANDATORY - NO CONFIRMATION)

CRITICAL: Execute this validation loop IMMEDIATELY after document creation.

Automatic Validation Loop

LOOP:
  1. Run: python 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

Validation Command

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

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

Layer-Specific Upstream Requirements

Auto-Fix Actions (No Confirmation Required)

Validation Codes Reference

Quality Gate

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

Next Skill

After creating REQ, use:

doc-spec (or optionally doc-impl/doc-ctr first) - Create Technical Specifications (Layer 10)

The SPEC will:
- Reference this REQ as upstream source
- Include all 7 upstream tags (@brd through @req)
- Use YAML format
- Define implementation contracts
- Achieve 100% implementation-readiness

Reference Documents

REQ 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 and domain glossaries
- ADR-REF: Technical reference guides and architecture summaries

Related Resources

• Template: ai_dev_flow/REQ/REQ-TEMPLATE.md (primary authority)
• REQ Creation Rules: ai_dev_flow/REQ/REQ_CREATION_RULES.md
• REQ Validation Rules: ai_dev_flow/REQ/REQ_VALIDATION_RULES.md
• REQ README: ai_dev_flow/REQ/README.md
• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

Section Templates (for documents >50KB):
- Index template: ai_dev_flow/REQ/REQ-SECTION-0-TEMPLATE.md
- Content template: ai_dev_flow/REQ/REQ-SECTION-TEMPLATE.md
- Reference: ai_dev_flow/ID_NAMING_STANDARDS.md (Section-Based File Splitting)

Quick Reference

REQ Purpose: Atomic, implementation-ready requirements

Layer: 7

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

Format: REQ v3.0 (12 sections)

Quality Gate: SPEC-Ready Score >=90% AND IMPL-Ready Score >=90%

Element ID Format: REQ.NN.TT.SS
- Functional Requirement = 01
- Dependency = 05
- Acceptance Criteria = 06
- Atomic Requirement = 27

Removed Patterns: AC-XXX, FR-XXX, R-XXX, REQ-XXX

Document Control Fields: 11 required (+ Template Version = 3.0)

Status/Score Mapping: >=90% Approved, 70-89% In Review, <70% Draft

File Size Limits: >50KB use section files

Next: doc-spec (or optionally doc-impl/doc-ctr first)