doc-spec

Create Technical Specifications (SPEC) - Layer 10 artifact in the SDD workflow that defines implementation-ready specifications in YAML format, providing complete technical details for code generation.

Layer: 10

Upstream: BRD (Layer 1), PRD (Layer 2), EARS (Layer 3), BDD (Layer 4), ADR (Layer 5), SYS (Layer 6), REQ (Layer 7), IMPL (Layer 8), CTR (Layer 9)

Downstream Artifacts: TASKS (Layer 11), Code (Layer 12)

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/ docs/IMPL/ docs/CTR/ 2>/dev/null

```

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

Before creating SPEC, read:

1. Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md
2. Upstream REQ: Read atomic requirements (PRIMARY SOURCE)
3. Upstream CTR: Read contracts if Layer 9 created
4. Template: ai_dev_flow/SPEC/SPEC-TEMPLATE.yaml
5. Creation Rules: ai_dev_flow/SPEC/SPEC_CREATION_RULES.md
6. Validation Rules: ai_dev_flow/SPEC/SPEC_VALIDATION_RULES.md
7. Validation Script: ./ai_dev_flow/scripts/validate_spec_template.sh (under development - use template for manual validation until available)

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

Pattern: SPEC-00_.md, SPEC-00_.yaml

Document Types:

• Index documents (SPEC-00_index.md)
• Traceability matrix templates (SPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md)
• Glossaries, registries, checklists

Rationale: Reserved ID 000 documents are framework infrastructure (indexes, templates, reference materials), not project artifacts requiring traceability or quality gates.

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

Use doc-spec when:

• Have completed BRD through REQ (Layers 1-7)
• Ready to create implementation-ready specifications
• Preparing for code generation or implementation
• Need complete technical details in structured format
• You are at Layer 10 of the SDD workflow

1. YAML Format (MANDATORY)

Format: Pure YAML (not markdown)

Structure:

```yaml

# SPEC-NN: [Specification Title]

metadata:

spec_id: SPEC-01

title: "Order Validation Service Specification"

version: "1.0.0"

created_date: "2025-01-15"

updated_date: "2025-01-15"

status: "approved"

owner: "team-backend"

task_ready_score: "✅ 95% (Target: ≥90%)"

cumulative_tags:

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.26.01"]

req: ["REQ.01.27.01"]

impl: ["IMPL.01.29.01"] # optional

contracts: ["CTR-01"] # optional

overview:

purpose: "Define trade order validation service implementation"

scope: "Validate trade orders against position limits and business rules"

requirements:

- "REQ-risk-limits-01"

- "REQ-risk-limits-02"

architecture:

pattern: "layered"

layers:

- name: "controller"

technology: "FastAPI"

description: "REST API endpoint handlers"

- name: "service"

technology: "Python"

description: "Business logic and validation"

- name: "repository"

technology: "SQLAlchemy"

description: "Database access layer"

interfaces:

api_endpoints:

- endpoint: "/api/v1/trades/validate"

method: "POST"

contract_ref: "CTR-01"

authentication: "Bearer token"

rate_limit: "@threshold: PRD.NN.limit.api.requests_per_second"

rate_limit_window: "1min"

data_models:

- model: "TradeOrderRequest"

schema_ref: "CTR-01#/components/schemas/TradeOrderRequest"

- model: "ValidationResponse"

schema_ref: "CTR-01#/components/schemas/ValidationResponse"

implementation:

modules:

- name: "controllers/trade_validation_controller.py"

purpose: "API endpoint handlers"

dependencies: ["services/trade_validator.py"]

- name: "services/trade_validator.py"

purpose: "Business logic and validation"

dependencies:

- "repositories/position_repository.py"

- "models/trade_order.py"

- name: "repositories/position_repository.py"

purpose: "Database access for positions"

dependencies: ["database/connection.py"]

functions:

- name: "validate_trade_order"

module: "services/trade_validator.py"

signature: "async def validate_trade_order(order: TradeOrderRequest) -> ValidationResponse"

purpose: "Validate trade order against all rules"

algorithm:

- "1. Validate symbol exists"

- "2. Check quantity is positive"

- "3. Validate price within range"

- "4. Check position limits"

- "5. Return validation result"

error_handling:

error_codes:

- code: "INVALID_SYMBOL"

http_status: 400

message: "Symbol not found in approved list"

recovery: "user_correction"

- code: "LIMIT_EXCEEDED"

http_status: 403

message: "Position limit exceeded"

recovery: "reduce_position"

configuration:

environment_variables:

- name: "MAX_POSITION_DELTA"

type: "float"

default: "0.50"

required: true

feature_flags:

- name: "enable_strict_validation"

default: false

description: "Enable enhanced validation rules"

testing:

unit_tests:

- test: "test_validate_valid_order"

module: "tests/unit/test_trade_validator.py"

coverage_target: 95

integration_tests:

- test: "test_validation_endpoint"

module: "tests/integration/test_trade_api.py"

performance_tests:

- test: "test_validation_latency"

target: "P95 < 50ms"

deployment:

container:

image: "trade-validator:1.0.0"

base: "python:3.11-slim"

resources:

cpu: "1000m"

memory: "512Mi"

scaling:

min_replicas: 2

max_replicas: 10

target_cpu: 70

monitoring:

metrics:

- name: "validation_latency_ms"

type: "histogram"

labels: ["endpoint", "status"]

- name: "validation_errors_total"

type: "counter"

labels: ["error_code"]

alerts:

- alert: "HighValidationLatency"

condition: "P95 > 100ms"

severity: "warning"

traceability:

upstream_sources:

- artifact: "BRD-01"

sections: ["section-3"]

- artifact: "PRD-01"

sections: ["feature-2"]

- artifact: "REQ-risk-limits-01"

sections: ["all"]

downstream_artifacts:

- "TASKS-01"

- "Code: src/services/trade_validator.py"

```

2. Element ID Format (MANDATORY)

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

| Element Type | Code | Example |

|--------------|------|---------|

| Step | 15 | SPEC.02.15.01 |

| Interface | 16 | SPEC.02.16.01 |

| Data Model | 17 | SPEC.02.17.01 |

| Validation Rule | 21 | SPEC.02.21.01 |

| Specification Element | 28 | SPEC.02.28.01 |

> REMOVED PATTERNS - Do NOT use legacy formats:

> - STEP-XXX - Use SPEC.NN.15.SS instead

> - IF-XXX or INT-XXX - Use SPEC.NN.16.SS instead

> - DM-XXX or MODEL-XXX - Use SPEC.NN.17.SS instead

> - VR-XXX - Use SPEC.NN.21.SS instead

Reference: [ID_NAMING_STANDARDS.md - Cross-Reference Link Format](../ai_dev_flow/ID_NAMING_STANDARDS.md#cross-reference-link-format-mandatory)

3. Required Top-Level Sections

MANDATORY Sections:

1. metadata: Spec ID, title, version, dates, status, owner, task_ready_score
2. cumulative_tags: All upstream tags (7-9 tags depending on layers)
3. overview: Purpose, scope, requirements
4. architecture: Pattern, layers, technologies
5. interfaces: API endpoints, data models
6. implementation: Modules, functions, algorithms
7. error_handling: Error codes, HTTP status, recovery
8. configuration: Environment variables, feature flags
9. testing: Unit, integration, performance tests
10. deployment: Container, resources, scaling
11. monitoring: Metrics, alerts, logging
12. traceability: Upstream sources, downstream artifacts

4. TASKS-Ready Scoring System

Purpose: Measures SPEC maturity and readiness for progression to TASKS implementation planning.

Format in Metadata:

```yaml

metadata:

task_ready_score: "✅ 95% (Target: ≥90%)"

```

Status and TASKS-Ready Score Mapping:

| TASKS-Ready Score | Required Status |

|-------------------|-----------------|

| ≥90% | approved |

| 70-89% | in_review |

| <70% | draft |

Scoring Criteria:

• YAML Completeness (25%): All metadata fields, traceability chain, all sections populated
• Interface Definitions (25%): External APIs with CTR contracts, internal interfaces, data schemas
• Implementation Specifications (25%): Behavior enables code generation, performance/security quantifiable
• Code Generation Readiness (25%): Machine-readable fields, TASKS-ready metadata

Quality Gate: Score <90% prevents TASKS artifact creation.

5. Threshold Registry Integration

Purpose: Prevent magic numbers by referencing centralized threshold registry.

When @threshold Tag is Required: Use for ALL quantitative values that are:

• Performance configurations (latencies, throughput, IOPS)
• Timeout configurations (connection, read, write timeouts)
• Rate limiting values (requests per second, burst limits)
• Resource limits (memory, CPU, storage)
• Circuit breaker configurations

@threshold Tag Format in YAML:

```yaml

# String value format

performance:

p95_latency_ms: "@threshold: PRD.NN.perf.api.p95_latency"

# Comment format for documentation

timeout:

request_ms: 5000 # @threshold: PRD.NN.timeout.request.sync

```

Invalid (hardcoded values):

```yaml

performance:

p95_latency_ms: 200

timeout:

request_ms: 5000

rate_limit:

requests_per_second: 100

```

Valid (registry references):

```yaml

performance:

p95_latency_ms: "@threshold: PRD.NN.perf.api.p95_latency"

timeout:

request_ms: "@threshold: PRD.NN.timeout.request.sync"

rate_limit:

requests_per_second: "@threshold: PRD.NN.limit.api.requests_per_second"

```

6. cumulative_tags Field (CRITICAL)

CRITICAL: SPEC must include cumulative_tags section with ALL upstream tags

Element Type Codes for Cumulative Tags:

| Tag | Artifact | Element Type | Code |

|-----|----------|--------------|------|

| brd | BRD | Business Requirement | 01 |

| prd | PRD | Product Feature | 07 |

| ears | EARS | EARS Statement | 25 |

| bdd | BDD | Scenario | 14 |

| adr | ADR | Document reference | (dash notation) |

| sys | SYS | System Requirement | 26 |

| req | REQ | Atomic Requirement | 27 |

| impl | IMPL | Implementation Phase | 29 |

| contracts | CTR | Document reference | (dash notation) |

Format (maximum - IMPL and CTR included):

```yaml

cumulative_tags:

brd: ["BRD.01.01.03", "BRD.01.01.05"]

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"]

sys: ["SYS.01.26.01", "SYS.01.26.07"]

req: ["REQ.01.27.01"]

impl: ["IMPL.01.29.01"]

contracts: ["CTR-01"]

```

Format (minimum - IMPL and CTR skipped):

```yaml

cumulative_tags:

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.26.01"]

req: ["REQ.01.27.01"]

```

Tag Count: 7-9 tags (minimum 7, maximum 9)

7. contract_ref Field

Purpose: Link SPEC to CTR (if Layer 9 created)

Format:

```yaml

interfaces:

api_endpoints:

- endpoint: "/api/v1/trades/validate"

method: "POST"

contract_ref: "CTR-01" # Link to contract

contract_path: "#/paths/~1api~1v1~1trades~1validate/post" # JSON Pointer

data_models:

- model: "TradeOrderRequest"

schema_ref: "CTR-01#/components/schemas/TradeOrderRequest"

```

8. Implementation Readiness

100% Implementation-Ready: SPEC must contain ALL information needed to write code

Checklist:

• [ ] All modules identified with file paths
• [ ] All functions identified with signatures
• [ ] All algorithms documented step-by-step
• [ ] All data models linked to schemas
• [ ] All error codes defined
• [ ] All configuration specified
• [ ] All tests specified
• [ ] Deployment requirements complete

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.01 → Points to element 01.01 inside document BRD-017.md

For hierarchical requirements (BRD, PRD, EARS, BDD, SYS, REQ, IMPL):

• Always use: TYPE.NN.TT.SS (dot separator, 4-segment unified format)
• Never use: TYPE-NN:NNN (colon separator - DEPRECATED)
• Never use: TYPE.NN.TT (3-segment format - DEPRECATED)

Examples:

• @brd: BRD.17.01.01 ✅
• @brd: BRD.017.001 ❌ (old 3-segment format)

Tier 1: Errors (Blocking)

| Check | Description |

|-------|-------------|

| CHECK 1 | YAML Syntax Validation (parseable) |

| CHECK 2 | Required Metadata Fields (version, status, task_ready_score) |

| CHECK 3 | TASKS-Ready Score format (✅ emoji + percentage + target) |

| CHECK 4 | Complete Traceability Chain (cumulative_tags section) |

| CHECK 5 | Element ID Format (SPEC.NN.TT.SS) |

Tier 2: Warnings (Recommended)

| Check | Description |

|-------|-------------|

| CHECK 6 | Interface Specifications (CTR contract references) |

| CHECK 7 | Implementation Readiness (code generation enabling) |

| CHECK 8 | Code Generation Compatibility (TASKS creation) |

Tier 3: Info

| Check | Description |

|-------|-------------|

| CHECK 9 | Threshold Registry Integration (@threshold references) |

| CHECK 10 | Performance benchmarks defined |

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
• REQ (Layer 7) - Atomic requirements (PRIMARY SOURCE)
• IMPL (Layer 8) - Implementation approach (optional)
• CTR (Layer 9) - Data contracts (optional)

Downstream Artifacts:

• TASKS (Layer 11) - Task breakdown
• Code (Layer 12) - Implementation code
• Tests (Layer 13) - Test suites

Same-Type Document Relationships (conditional):

• @related-spec: SPEC-NN - SPECs sharing implementation context
• @depends-spec: SPEC-NN - SPEC that must be implemented first

Step 1: Read Upstream Artifacts

Focus on REQ (Layer 7) and optionally CTR (Layer 9).

Step 2: Reserve ID Number

Check docs/SPEC/ for next available ID number (or create docs/SPEC/ directory if first SPEC).

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

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

Step 3: Create SPEC File

File naming: docs/SPEC/SPEC-NN_{slug}.yaml

Example: docs/SPEC/SPEC-01_trade_validation.yaml

IMPORTANT: Pure YAML format (NOT markdown)

Note: Templates and examples are in ai_dev_flow/SPEC/ while project-specific SPECs go in docs/SPEC/.

Step 4: Fill Metadata Section

Complete spec_id, title, version, dates, status, owner, task_ready_score.

Step 5: Add Cumulative Tags

Include all 7-9 upstream tags (brd through req/impl/contracts).

Step 6: Define Overview

Purpose, scope, and requirements list.

Step 7: Specify Architecture

Pattern, layers, and technologies (reference ADR decisions).

Step 8: Define Interfaces

API endpoints (with contract_ref), data models (with schema_ref).

Step 9: Document Implementation

Modules (file paths), functions (signatures), algorithms (step-by-step).

Step 10: Specify Error Handling

Error codes, HTTP status, messages, recovery procedures.

Step 11: Define Configuration

Environment variables, feature flags, defaults. Use @threshold for quantitative values.

Step 12: Specify Testing

Unit tests, integration tests, performance tests with targets.

Step 13: Define Deployment

Container, resources, scaling, environment.

Step 14: Add Monitoring

Metrics, alerts, logging requirements.

Step 15: Add Traceability

Upstream sources and downstream artifacts.

Step 16: Create/Update Traceability Matrix

MANDATORY: Create or update docs/SPEC/SPEC-00_TRACEABILITY_MATRIX.md (use template from ai_dev_flow/SPEC/SPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md)

Step 17: Validate SPEC

```bash

# YAML validation

yamllint docs/SPEC/SPEC-01_*.yaml

# Schema validation (use SPEC_SCHEMA.yaml as reference)

# Manual: Compare against ai_dev_flow/SPEC/SPEC_SCHEMA.yaml structure

# Cumulative tagging validation

python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact SPEC-01 --expected-layers brd,prd,ears,bdd,adr,sys,req,impl,contracts --strict

# Cross-document validation

python ai_dev_flow/scripts/validate_cross_document.py --document docs/SPEC/SPEC-01_*.yaml

```

Step 18: Commit Changes

Commit SPEC file and traceability matrix.

Automated Validation

```bash

# YAML validation

yamllint docs/SPEC/SPEC-01_*.yaml

# Schema validation (use SPEC_SCHEMA.yaml as reference)

# Manual: Compare against ai_dev_flow/SPEC/SPEC_SCHEMA.yaml structure

# Cumulative tagging validation

python ai_dev_flow/scripts/validate_tags_against_docs.py \

--artifact SPEC-01 \

--expected-layers brd,prd,ears,bdd,adr,sys,req,impl,contracts \

--strict

# Cross-document validation

python ai_dev_flow/scripts/validate_cross_document.py --document docs/SPEC/SPEC-01_*.yaml

```

Manual Checklist

• [ ] Pure YAML format (not markdown)
• [ ] Metadata section complete with task_ready_score
• [ ] cumulative_tags section with 7-9 upstream tags
• [ ] Overview defines purpose and scope
• [ ] Architecture references ADR decisions
• [ ] Interfaces link to CTR (if Layer 9 created)
• [ ] Implementation specifies modules with file paths
• [ ] Functions have signatures and algorithms
• [ ] Error handling complete
• [ ] Configuration uses @threshold for quantitative values
• [ ] Testing requirements defined
• [ ] Deployment requirements complete
• [ ] Monitoring specified
• [ ] Traceability links to upstream/downstream
• [ ] 100% implementation-ready
• [ ] Element IDs use SPEC.NN.TT.SS format

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.

1. Markdown format: SPEC must be pure YAML, not markdown
2. Missing cumulative_tags: Must include all 7-9 upstream tags
3. No contract_ref: Must link to CTR if Layer 9 created
4. Vague implementation: Must specify exact file paths and signatures
5. Missing algorithms: Functions need step-by-step algorithms
6. Incomplete: Must be 100% implementation-ready
7. Hardcoded values: Use @threshold for performance/timeout/rate limits
8. Wrong element IDs: Use SPEC.NN.TT.SS, not legacy STEP-XXX, IF-XXX, DM-XXX
9. Wrong cumulative tag codes: Use correct element type codes (EARS=25, BDD=14, SYS=26, REQ=27, IMPL=29)

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

```

Validation Command

```bash

# Per-document validation (Phase 1)

python ai_dev_flow/scripts/validate_cross_document.py --document docs/SPEC/SPEC-NN_slug.yaml --auto-fix

# Layer validation (Phase 2) - run when all SPEC documents complete

python ai_dev_flow/scripts/validate_cross_document.py --layer SPEC --auto-fix

```

Layer-Specific Upstream Requirements

| This Layer | Required Upstream Tags | Count |

|------------|------------------------|-------|

| SPEC (Layer 10) | @brd, @prd, @ears, @bdd, @adr, @sys, @req (+ @impl, @ctr if created) | 7-9 tags |

Auto-Fix Actions (No Confirmation Required)

| Issue | Fix Action |

|-------|------------|

| Missing upstream 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 next document until Phase 1 validation passes with 0 errors.

---

After creating SPEC, use:

doc-tasks - Create Task Breakdown (Layer 11)

The TASKS will:

• Reference this SPEC as upstream source
• Include all 8-10 upstream tags
• Break SPEC into actionable tasks
• Provide AI-structured TODO format

SPEC 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: Technical reference guides (API quick references, implementation guides)

• Template: ai_dev_flow/10_SPEC/SPEC-TEMPLATE.yaml (primary authority)
• SPEC Creation Rules: ai_dev_flow/10_SPEC/SPEC_CREATION_RULES.md
• SPEC Validation Rules: ai_dev_flow/10_SPEC/SPEC_VALIDATION_RULES.md
• SPEC Schema: ai_dev_flow/10_SPEC/SPEC_SCHEMA.yaml
• SPEC README: ai_dev_flow/10_SPEC/README.md
• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

SPEC Purpose: Implementation-ready technical specifications

Layer: 10

Element ID Format: SPEC.NN.TT.SS

• Step = 15
• Interface = 16
• Data Model = 17
• Validation Rule = 21
• Specification Element = 28

Removed Patterns: STEP-XXX, IF-XXX, INT-XXX, DM-XXX, MODEL-XXX, VR-XXX

Tags Required: @brd through @req/impl/contracts (7-9 tags)

Format: Pure YAML (not markdown)

Key Features:

• cumulative_tags section (CRITICAL)
• contract_ref field (links to CTR)
• schema_ref field (links to data models)
• @threshold references for quantitative values
• 100% implementation-ready
• All modules, functions, algorithms specified

TASKS-Ready Score: ≥90% required for "approved" status

Quality Gate: Must be 100% implementation-ready

Next: doc-tasks