doc-spec Purpose
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)
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/ docs/IMPL/ docs/CTR/ 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 SPEC, read:
Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md Upstream REQ: Read atomic requirements (PRIMARY SOURCE) Upstream CTR: Read contracts if Layer 9 created Template: ai_dev_flow/SPEC/SPEC-TEMPLATE.yaml Creation Rules: ai_dev_flow/SPEC/SPEC_CREATION_RULES.md Validation Rules: ai_dev_flow/SPEC/SPEC_VALIDATION_RULES.md Validation Script: ./ai_dev_flow/scripts/validate_spec_template.sh (under development - use template for manual validation until available) Reserved ID Exemption (SPEC-00_*)
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.
When to Use This Skill
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 SPEC-Specific Guidance 1. YAML Format (MANDATORY)
Format: Pure YAML (not markdown)
Structure:
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"
- 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
- Required Top-Level Sections
MANDATORY Sections:
metadata: Spec ID, title, version, dates, status, owner, task_ready_score cumulative_tags: All upstream tags (7-9 tags depending on layers) overview: Purpose, scope, requirements architecture: Pattern, layers, technologies interfaces: API endpoints, data models implementation: Modules, functions, algorithms error_handling: Error codes, HTTP status, recovery configuration: Environment variables, feature flags testing: Unit, integration, performance tests deployment: Container, resources, scaling monitoring: Metrics, alerts, logging 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:
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.
- 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:
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):
performance: p95_latency_ms: 200 timeout: request_ms: 5000 rate_limit: requests_per_second: 100
Valid (registry references):
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"
- 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):
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):
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)
- contract_ref Field
Purpose: Link SPEC to CTR (if Layer 9 created)
Format:
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"
- 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 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.01 → Points to element 01.01 inside document BRD-017.md Unified Element ID Format (MANDATORY)
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) Validation Checks 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/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 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 Creation Process 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
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.
Validation Automated Validation
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.
Common Pitfalls Markdown format: SPEC must be pure YAML, not markdown Missing cumulative_tags: Must include all 7-9 upstream tags No contract_ref: Must link to CTR if Layer 9 created Vague implementation: Must specify exact file paths and signatures Missing algorithms: Functions need step-by-step algorithms Incomplete: Must be 100% implementation-ready Hardcoded values: Use @threshold for performance/timeout/rate limits Wrong element IDs: Use SPEC.NN.TT.SS, not legacy STEP-XXX, IF-XXX, DM-XXX Wrong cumulative tag codes: Use correct element type codes (EARS=25, BDD=14, SYS=26, REQ=27, IMPL=29) 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
Validation Command
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.
Next Skill
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 Reference Documents
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) Related Resources 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 Quick Reference
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