doc-req

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:

   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 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_ssd_flow/07_REQ/REQ-MVP-TEMPLATE.md
4. Creation Rules: ai_dev_ssd_flow/07_REQ/REQ-MVP-TEMPLATE.md
5. Validation Rules: ai_dev_ssd_flow/07_REQ/REQ_MVP_SCHEMA.yaml
6. Quality Gate Validation: ai_dev_ssd_flow/07_REQ/REQ_MVP_QUALITY_GATE_VALIDATION.md
7. 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:

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)

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**:
- [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}.{HASH} (3 segments, dot-separated)

Element Type	Code	Example
Functional Requirement	01	REQ.02.0101
Dependency	05	REQ.02.0501
Acceptance Criteria	06	REQ.02.0601
Atomic Requirement	27	REQ.02.2701

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.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.0103 -> 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.0103
@prd: PRD.01.0702
@ears: EARS.01.2501
@bdd: BDD.01.1401
@adr: ADR-033, ADR-045
@sys: SYS.01.0101, SYS.01.0207

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

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)

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

1. Incomplete sections: All 11 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.xxxx 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_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.xxxx (3-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-TEMPLATE.md

• REQ Validation Rules: ai_dev_ssd_flow/07_REQ/REQ_MVP_SCHEMA.yaml

• 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.xxxx

• 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