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:

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

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 REQ, read:

• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

• Upstream SYS: Read system requirements driving this REQ

• Template: ai_dev_ssd_flow/07_REQ/REQ-MVP-TEMPLATE.md

• Creation Rules: ai_dev_ssd_flow/07_REQ/REQ_MVP_CREATION_RULES.md

• Validation Rules: ai_dev_ssd_flow/07_REQ/REQ_MVP_VALIDATION_RULES.md

• Quality Gate Validation: ai_dev_ssd_flow/07_REQ/REQ_MVP_QUALITY_GATE_VALIDATION.md

• Validation Script: ./ai_dev_ssd_flow/07_REQ/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 MVP Format (11 Required Sections)

CRITICAL: REQ MVP uses streamlined 11-section structure

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

Core Sections:

• Description: Atomic requirement + SHALL/SHOULD/MAY language + context + scenario

• Functional Requirements: Core capabilities + business rules

• Interface Specifications: Protocol/ABC definitions + DTOs + REST endpoints

• Data Schemas: JSON Schema + Pydantic models + Database schema

• Error Handling Specifications: Exception catalog + error response schema + circuit breaker config

• Configuration Specifications: YAML schema + environment variables + validation

• Quality Attributes: Performance targets (p50/p95/p99) + reliability/security/scalability

• Implementation Guidance: Algorithms/patterns + concurrency/async + dependency injection

• Acceptance Criteria: >=15 measurable criteria covering functional/error/quality/data/integration

• Verification Methods: BDD scenarios + unit/integration/contract/performance tests

• Traceability: Section 7 format with cumulative tags (6 required)

Note: Change History is intentionally omitted in REQ MVP.

2. Document Control Requirements (11 Mandatory Fields)

Field Format Example

Status Approved/In Review/Draft Approved

Version Semantic X.Y.Z 2.0.1

Date Created ISO 8601 2025-11-18

Last Updated ISO 8601 2025-11-19

Author Name/Role System Architect

Priority Level (P-level) High (P2)

Category Type Functional

Source Document DOC-ID section X.Y.Z SYS-02 section 3.1.1

Verification Method Method type BDD + Integration Test

Assigned Team Team name IB Integration Team

SPEC-Ready Score Format with emoji

=90% (Target: >=90%)

IMPL-Ready Score Format with emoji

=90% (Target: >=90%)

Template Version Must be 3.0 3.0

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:

Ready Score Required Status

= 90% Approved

70-89% In Review

< 70% Draft

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:

• 1. Description
• 2. Functional Requirements
• 3. Interface Specifications
• 4. Data Schemas
• 5. Error Handling Specifications
• 6. Configuration Specifications
• 7. Quality Attributes
• 8. Implementation Guidance
• 9. Acceptance Criteria
• 10. Verification Methods
• 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)

Element Type Code Example

Functional Requirement 01 REQ.02.01.01

Dependency 05 REQ.02.05.01

Acceptance Criteria 06 REQ.02.06.01

Atomic Requirement 27 REQ.02.27.01

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:

Notation Format Artifacts Purpose

Dash TYPE-NN ADR, SPEC, CTR 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.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):

@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

Category
REQ Usage
Example Key

perf.*

Performance acceptance criteria
perf.api.p95_latency

timeout.*

Circuit breaker, connection configs
timeout.circuit_breaker.reset

retry.*

Retry policy configurations
retry.max_attempts

limit.*

Rate limits, resource limits
limit.api.requests_per_second

resource.*

Memory, CPU constraints
resource.memory.max_heap

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 docs/07_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

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

Location Options:

- Standard: docs/07_REQ/REQ-NN_{slug}/REQ-NN_{slug}.md

- Domain-based: docs/07_REQ/{domain}/REQ-NN_{slug}/REQ-NN_{slug}.md

- Subdomain: docs/07_REQ/{domain}/{subdomain}/REQ-NN_{slug}/REQ-NN_{slug}.md

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

# Create target directory (ALWAYS use nested folder)
mkdir -p docs/07_REQ/REQ-NN_{slug}/
# OR for domain-based structure
mkdir -p docs/07_REQ/{domain}/REQ-NN_{slug}/

CRITICAL: Never create REQ files directly in docs/07_REQ/
 without a nested folder 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 11 Required Sections

Critical: REQ MVP requires all 11 sections for >=90% SPEC-readiness

- Description: Atomic requirement + SHALL/SHOULD/MAY language

- Functional Requirements: Core capabilities + business rules

- Interface Specifications: APIs, endpoints, contracts, Protocol/ABC class

- Data Schemas: Models, validation, constraints, Pydantic/dataclass

- Error Handling Specifications: Error codes, recovery, exception definitions

- Configuration Specifications: Settings, feature flags, YAML config

- Quality Attributes: Performance, security, scalability with thresholds

- Implementation Guidance: Technical approach, patterns

- Acceptance Criteria: >=15 measurable criteria

- Verification Methods: BDD scenarios, tests

- Traceability: Cumulative tags (6 tags)

Note: Change History is intentionally omitted in REQ MVP.

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_ssd_flow/07_REQ/REQ-00_TRACEABILITY_MATRIX-TEMPLATE.md

Step 9: Validate REQ

./ai_dev_ssd_flow/07_REQ/scripts/validate_req_template.sh docs/07_REQ/REQ-NN_*/REQ-NN_*.md

python ai_dev_ssd_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)

Check
Description
Type

CHECK 1
Required 11 sections
Error

CHECK 2
Document Control (11 fields)
Error

CHECK 3
Traceability structure
Error/Warning

CHECK 4
Legacy (deprecated)
Info

CHECK 5
Version format (X.Y.Z)
Error

CHECK 6
Date format (ISO 8601)
Error

CHECK 7
Priority format (P1-P4)
Warning

CHECK 8
Source document format
Warning

CHECK 9
SPEC-Ready Score
Error/Warning

CHECK 10
Template Version (3.0)
Error

CHECK 11
Change History
Error/Warning

CHECK 12
Filename/ID format
Error

CHECK 13
Resource tag (Template 2.0)
Error

CHECK 14
Cumulative tagging (6 tags)
Error

CHECK 15
Complete upstream chain
Error

CHECK 16
Link resolution
Error/Warning

CHECK 17
Traceability matrix
Warning

CHECK 18
SPEC-Ready content
Warning

CHECK 19
IMPL-Ready Score
Error

CHECK 20
Element ID format compliance
Error

Validation Tiers

Tier
Type
Exit Code
Description

Tier 1
Errors
1
Blocking - must fix before commit

Tier 2
Warnings
0
Quality issues - recommended to fix

Tier 3
Info
0
Informational - no action required

Pre-Commit Hooks

REQ validation is automatically enforced via pre-commit hooks:

- id: req-core-validator
  name: Validate REQ core checks (validator, framework library)
  entry: bash ai_dev_ssd_flow/07_REQ/scripts/req_core_validator_hook.sh
  stages: [pre-commit]

- id: req-quality-gate
  name: Validate REQ quality gates
  entry: bash ai_dev_ssd_flow/07_REQ/scripts/req_quality_gate_hook.sh
  stages: [pre-commit]

- id: req-spec-ready-score
  name: Validate REQ SPEC-Ready score (≥90%)
  entry: bash ai_dev_ssd_flow/07_REQ/scripts/req_spec_ready_score_hook.sh
  stages: [pre-commit]

Manual execution (for testing without committing):

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

Quality Gates Enforced:

- ✅ REQ structure compliance (11 sections MVP)

- ✅ SPEC-Ready score ≥90% for Approved status

- ✅ Metadata and tags (req, layer-7-artifact)

- ✅ Upstream traceability (@brd, @prd, @ears, @bdd, @adr, @sys - 6 tags)

- ✅ No placeholder text in approved documents

- ✅ Atomic requirements (single responsibility)

- ✅ Measurable acceptance criteria (≥15 criteria)

- ✅ Interface specifications with Protocol/ABC classes

- ✅ Data schemas (Pydantic/JSON Schema)

- ✅ Error handling specifications

- ✅ Configuration specifications (YAML schema)

- ✅ Quality attributes with @threshold tags

- ✅ Cross-linking between related REQs

Automated Validation

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

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

# Cumulative tagging validation
python ai_dev_ssd_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 11 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_ssd_flow/DIAGRAM_STANDARDS.md
 and mermaid-gen
 skill.

Common Pitfalls

- Incomplete sections: All 11 sections mandatory for SPEC-readiness

- Missing new sections: Sections 3-7 are new in v3.0 - don't skip them

- Low readiness scores: Both SPEC-Ready and IMPL-Ready must achieve >=90%

- Non-atomic requirements: Each REQ must be single, testable unit

- Missing cumulative tags: Layer 7 must include all 6 upstream tags

- Vague acceptance criteria: Must be measurable and testable

- Hardcoded values: Use @threshold references, not magic numbers

- Legacy element IDs: Use REQ.NN.TT.SS
 format, not AC-XXX or FR-XXX

- 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_ssd_flow/scripts/validate_cross_document.py --document docs/07_REQ/REQ-NN_slug/REQ-NN_slug.md --auto-fix

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

Layer-Specific Upstream Requirements

This Layer
Required Upstream Tags
Count

REQ (Layer 7)
@brd, @prd, @ears, @bdd, @adr, @sys
6 tags

Auto-Fix Actions (No Confirmation Required)

Issue
Fix Action

Missing @brd/@prd/@ears/@bdd/@adr/@sys tag
Add with upstream document reference

Invalid tag format
Correct to TYPE.NN.TT.SS (4-segment) or TYPE-NN 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 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_ssd_flow/07_REQ/REQ-MVP-TEMPLATE.md
 (primary authority)

- 
REQ Creation Rules: ai_dev_ssd_flow/07_REQ/REQ_MVP_CREATION_RULES.md

- 
REQ Validation Rules: ai_dev_ssd_flow/07_REQ/REQ_MVP_VALIDATION_RULES.md

- 
REQ README: ai_dev_ssd_flow/07_REQ/README.md

- 
Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

- 
Section Splitting Reference (for documents >50KB):

- 
Reference: ai_dev_ssd_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 MVP (11 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)

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
Updated to REQ v3.0 format (11 sections, SPEC-readiness scoring)
System

1.0
2026-02-08
Initial skill definition with YAML frontmatter standardization
System