doc-ctr Purpose
Create Data Contracts (CTR) - Optional Layer 9 artifact in the SDD workflow that defines API contracts, data schemas, and interface specifications using dual-file format (markdown + YAML).
Layer: 9 (Optional)
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)
Downstream Artifacts: SPEC (Layer 10), 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/ 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 CTR, read:
Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md Upstream REQ: Read atomic requirements (especially Section 3: Interface Specifications, Section 4: Data Schemas) Template: ai_dev_flow/CTR/CTR-TEMPLATE.md and CTR-TEMPLATE.yaml Creation Rules: ai_dev_flow/CTR/CTR_CREATION_RULES.md Validation Rules: ai_dev_flow/CTR/CTR_VALIDATION_RULES.md Validation Script: ./ai_dev_flow/scripts/validate_ctr.sh Reserved ID Exemption (CTR-00_*)
Scope: Documents with reserved ID 000 are FULLY EXEMPT from validation.
Pattern: CTR-00_.md, CTR-00_.yaml
Document Types:
Index documents (CTR-00_index.md) Traceability matrix templates (CTR-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 CTR-00_* pattern.
When to Use This Skill
Use doc-ctr when:
Have completed BRD through REQ (Layers 1-7) Need to define API contracts or data schemas Multiple teams/services need shared contracts Building microservices or distributed systems REQ Section 3 (Interface Specifications) needs formal contract This layer is OPTIONAL - skip if contracts are simple CTR-Specific Guidance 1. Mandatory Dual-File Format
Two files required for each contract (mandatory dual-file format: .md file + companion .yaml file):
Markdown File (.md):
Document Control section Contract overview Business context Usage examples Traceability
YAML File (.yaml):
OpenAPI 3.0 or JSON Schema Formal contract definition Validation rules Example payloads
Example:
ai_dev_flow/CTR/CTR-01_data_validation.md ai_dev_flow/CTR/CTR-01_data_validation.yaml
- Document Control Fields (9 Required) Field Required Description CTR ID Yes CTR-NN format Title Yes Contract name Status Yes Draft/In Review/Active/Deprecated Version Yes Semantic version (Major.Minor.Patch) Created Yes YYYY-MM-DD Author Yes Document author Owner Yes Contract owner Last Updated Yes YYYY-MM-DD SPEC-Ready Score Yes ✅ NN% (Target: ≥90%)
- Required Sections (Markdown File)
Document Control (MANDATORY - First section before all numbered sections)
Core Sections:
Contract Overview: Purpose, scope, version Business Context: Why this contract exists (link to REQ) Contract Definition: Reference to YAML file Usage Examples: Request/response examples Validation Rules: Schema validation, business rules Error Handling: Error codes and responses Traceability: Section 7 format with cumulative tags 4. Element ID Format (MANDATORY)
Pattern: CTR.{DOC_NUM}.{ELEM_TYPE}.{SEQ} (4 segments, dot-separated)
Element Type Code Example Interface 16 CTR.02.16.01 Data Model 17 CTR.02.17.01 Contract Clause 20 CTR.02.20.01
REMOVED PATTERNS - Do NOT use legacy formats:
INT-XXX - Use CTR.NN.16.SS instead MODEL-XXX - Use CTR.NN.17.SS instead CLAUSE-XXX - Use CTR.NN.20.SS instead IF-XXX - Use CTR.NN.16.SS instead DM-XXX - Use CTR.NN.17.SS instead CC-XXX - Use CTR.NN.20.SS instead
Reference: ID_NAMING_STANDARDS.md - Cross-Reference Link Format
- YAML Contract Format
OpenAPI 3.0 Format (for APIs):
openapi: 3.0.3 info: title: Data Validation API version: 1.0.0 description: Contract for data validation
paths: /api/v1/data/validate: post: summary: Validate data record operationId: validateDataRecord requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DataRequest' responses: '200': description: Validation successful content: application/json: schema: $ref: '#/components/schemas/ValidationResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse'
components: schemas: DataRequest: type: object required: - record_type - record_id - data - account_id properties: record_type: type: string pattern: ^[A-Z]{1,10}$ example: "METRIC" record_id: type: string format: uuid example: "abc123" data: type: object example: {} account_id: type: string format: uuid example: "123e4567-e89b-12d3-a456-426614174000"
ValidationResponse:
type: object
required:
- valid
- order_id
properties:
valid:
type: boolean
example: true
order_id:
type: string
format: uuid
example: "987f6543-e21c-43d2-b654-426614174111"
warnings:
type: array
items:
type: string
example: ["Price near market close"]
ErrorResponse:
type: object
required:
- error_code
- message
properties:
error_code:
type: string
example: "INVALID_SYMBOL"
message:
type: string
example: "Symbol 'XYZ' not found in approved list"
details:
type: object
additionalProperties: true
JSON Schema Format (for data models):
$schema: "http://json-schema.org/draft-07/schema#" name: DataProcessingConfig description: Configuration schema for data processing
type: object required: - max_batch_size - timeout_seconds - check_frequency
properties: max_batch_size: type: integer minimum: 1 maximum: 10000 description: Maximum records per batch example: 1000
timeout_seconds: type: integer minimum: 1 maximum: 300 description: Processing timeout in seconds example: 60
check_frequency: type: string enum: ["realtime", "1min", "5min", "15min"] description: How often to check processing status example: "1min"
alert_threshold: type: number minimum: 0 maximum: 1.0 description: Alert when queue depth exceeds this fraction default: 0.80 example: 0.80
- Usage Examples Section
Format:
Usage Examples
Example 1: Successful Validation
Request: ```json { "record_type": "METRIC", "record_id": "abc123", "data": {"value": 100}, "account_id": "123e4567-e89b-12d3-a456-426614174000" }
Response:
{ "valid": true, "order_id": "987f6543-e21c-43d2-b654-426614174111", "warnings": [] }
Example 2: Invalid Record Type
Request:
{ "record_type": "invalid", "record_id": "abc123", "data": {"value": 100}, "account_id": "123e4567-e89b-12d3-a456-426614174000" }
Response (400 Bad Request):
{ "error_code": "INVALID_RECORD_TYPE", "message": "Record type 'invalid' not found in approved list", "details": { "record_type": "invalid", "approved_types": ["METRIC", "EVENT", "LOG"] } }
7. Contract Versioning
Semantic Versioning: Major.Minor.Patch
Version Policy: - Major: Breaking changes (incompatible) - Minor: New features (backward compatible) - Patch: Bug fixes (backward compatible)
Example: ```yaml openapi: 3.0.3 info: title: Data Validation API version: 2.1.0 # Major.Minor.Patch description: | Version 2.1.0 (2025-01-15) - Added: optional 'warnings' field in response (minor) - Fixed: validation error for edge case data (patch)
Breaking changes from v1.x:
- Changed: account_id now requires UUID format (was string)
- SPEC-Ready Scoring System
Purpose: Measures CTR maturity and readiness for progression to Technical Specifications (SPEC) phase.
Format in Document Control:
| SPEC-Ready Score | ✅ 95% (Target: ≥90%) |
Status and SPEC-Ready Score Mapping:
SPEC-Ready Score Required Status ≥90% Active 70-89% In Review <70% Draft
Scoring Criteria:
Schema Completeness (35%): All endpoints/models defined, JSON Schema/OpenAPI validation passes, examples provided Error Handling (25%): All error codes documented, retry strategies specified, failure modes covered Quality Attributes (20%): Performance targets, SLA requirements, idempotency specified Traceability (10%): Upstream REQ/ADR linked, consumer/provider identified Documentation (10%): Usage examples, versioning policy, deprecation strategy
Quality Gate: Score <90% blocks SPEC artifact creation.
- Directory Organization by Service Type
Purpose: Organize contracts by service type for large projects (30+ contracts).
Structure:
CTR/ ├── agents/ # Agent-to-agent communication ├── mcp/ # MCP server contracts ├── infra/ # Infrastructure services └── shared/ # Cross-cutting contracts
When to Use:
<10 contracts: Flat directory 10-30 contracts: Optional subdirectories 30+ contracts: Mandatory subdirectories
Recommendation: Start flat, migrate to subdirectories when 3+ contracts per service type.
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) Cumulative Tagging Requirements
Layer 9 (CTR): Must include tags from Layers 1-8 (BRD through IMPL)
Tag Count: 7-8 tags (7 if IMPL skipped, 8 if IMPL included)
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
Format (if IMPL included):
Traceability
Required Tags (Cumulative Tagging Hierarchy - Layer 9): ```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.26.01 @req: REQ.01.27.03 @impl: IMPL.01.29.01
Format (if IMPL skipped):
@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.03
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 - especially Section 3) IMPL (Layer 8) - Implementation approach (optional)
Downstream Artifacts:
SPEC (Layer 10) - Technical specifications TASKS (Layer 11) - Task breakdown Code (Layer 12) - Implementation code Tests (Layer 13) - Test suites
Same-Type Document Relationships (conditional):
@related-ctr: CTR-NN - CTRs sharing API context @depends-ctr: CTR-NN - CTR that must be completed first Validation Checks Tier 1: Errors (Blocking) Check Description CHECK 1 Required Document Control Fields (9 fields) CHECK 2 Dual-File Format (both .md and .yaml exist) CHECK 3 SPEC-Ready Score format (✅ emoji + percentage + target) CHECK 4 YAML Schema Validation (OpenAPI/JSON Schema valid) CHECK 5 Cumulative Tagging (7-8 upstream tags) CHECK 6 Element ID Format (CTR.NN.TT.SS) Tier 2: Warnings (Recommended) Check Description CHECK 7 Usage Examples (request/response pairs) CHECK 8 Error Handling (error codes documented) CHECK 9 Versioning Policy (semantic versioning) CHECK 10 Validation Rules (schema validation specified) Tier 3: Info Check Description CHECK 11 Directory Organization (subdirectories for 30+ contracts) CHECK 12 Consumer/Provider identified Creation Process Step 1: Read Upstream Artifacts
Focus on REQ Section 3 (Interface Specifications) and Section 4 (Data Schemas).
Step 2: Reserve ID Number
Check ai_dev_flow/CTR/ for next available ID number.
ID Numbering Convention: Start with 2 digits and expand only as needed.
✅ Correct: CTR-01, CTR-99, CTR-102 ❌ Incorrect: CTR-001, CTR-009 (extra leading zero not required) Step 3: Create CTR Files (Dual Format)
Location Options:
Flat: docs/CTR/CTR-NN_{slug}.md + .yaml Service-based: docs/CTR/{service_type}/CTR-NN_{slug}.md + .yaml
On-Demand Folder Creation: Before saving, create the target directory if needed:
For 10+ contracts, create service-type subdirectory
mkdir -p docs/CTR/{service_type}/
Service Types (when 10+ contracts):
agents/ - Agent-to-agent communication mcp/ - MCP server contracts infra/ - Infrastructure services shared/ - Cross-cutting contracts
Example:
Flat: docs/CTR/CTR-01_data_validation.md + .yaml Subdirectory: docs/CTR/agents/CTR-01_data_validation.md + .yaml Step 4: Fill Document Control Section (Markdown)
Complete all 9 required fields including SPEC-Ready Score.
Step 5: Write Contract Overview (Markdown)
Summarize purpose, scope, and version.
Step 6: Define YAML Contract
Choose format:
OpenAPI 3.0 for REST APIs JSON Schema for data models AsyncAPI for event-driven systems (if applicable) Step 7: Add Usage Examples (Markdown)
Provide request/response examples with explanations.
Step 8: Document Validation Rules (Markdown)
Explain schema validation and business rules.
Step 9: Specify Error Handling (Markdown)
Document error codes and responses.
Step 10: Add Cumulative Tags
Include all 7-8 upstream tags (@brd through @req/impl).
Step 11: Create/Update Traceability Matrix
MANDATORY: Update ai_dev_flow/CTR/CTR-00_TRACEABILITY_MATRIX-TEMPLATE.md
Step 12: Validate CTR
YAML schema validation
yamllint ai_dev_flow/CTR/CTR-01_*.yaml
OpenAPI validation
openapi-spec-validator ai_dev_flow/CTR/CTR-01_*.yaml
Cumulative tagging
python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact CTR-01 --expected-layers brd,prd,ears,bdd,adr,sys,req,impl --strict
Step 13: Commit Changes
Commit both files (.md and .yaml) and traceability matrix.
Validation Automated Validation
Quality gates
scripts/validate_quality_gates.sh ai_dev_flow/CTR/CTR-01_*.md
YAML validation
yamllint ai_dev_flow/CTR/CTR-01_*.yaml
OpenAPI validation (if using OpenAPI)
openapi-spec-validator ai_dev_flow/CTR/CTR-01_*.yaml
CTR-specific validation (includes dual-file check)
./ai_dev_flow/scripts/validate_ctr.sh CTR-01
Cumulative tagging
python ai_dev_flow/scripts/validate_tags_against_docs.py \ --artifact CTR-01 \ --expected-layers brd,prd,ears,bdd,adr,sys,req,impl \ --strict
Manual Checklist Both files created (.md and .yaml) Document Control complete (9 fields) SPEC-Ready Score format correct (✅ NN% (Target: ≥90%)) Contract Overview clear Business Context explains why (links to REQ) YAML contract valid (OpenAPI/JSON Schema) Usage Examples comprehensive Error handling documented Validation rules specified Version number semantic (Major.Minor.Patch) Cumulative tags: @brd through @req/impl (7-8 tags) Element IDs use CTR.NN.TT.SS format 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 Single file only: Must create BOTH .md and .yaml files Invalid YAML: Must validate with yamllint and openapi-spec-validator Missing examples: Usage Examples section critical for adoption Vague validation: Schema validation must be precise and testable Missing cumulative tags: Layer 9 must include all 7-8 upstream tags Skipping when needed: Don't skip if multiple teams need shared contract Wrong element IDs: Use CTR.NN.TT.SS, not legacy INT-XXX, MODEL-XXX, CLAUSE-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/CTR/CTR-NN_slug.md --auto-fix
Layer validation (Phase 2) - run when all CTR documents complete
python ai_dev_flow/scripts/validate_cross_document.py --layer CTR --auto-fix
Layer-Specific Upstream Requirements This Layer Required Upstream Tags Count CTR (Layer 9) @brd, @prd, @ears, @bdd, @adr, @sys, @req (+ @impl if created) 7-8 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 CTR (or skipping this optional layer), use:
doc-spec - Create Technical Specifications (Layer 10)
The SPEC will:
Reference CTR (if created) or REQ as upstream source Include all 8-9 upstream tags Use YAML format Define implementation details Achieve 100% implementation-readiness Reference Documents
For supplementary documentation related to CTR artifacts:
Format: CTR-REF-NNN_{slug}.md Skill: Use doc-ref skill Validation: Minimal (non-blocking) Examples: API style guides, contract versioning policies Related Resources Template: ai_dev_flow/CTR/CTR-TEMPLATE.md (primary authority) Schema Template: ai_dev_flow/CTR/CTR-TEMPLATE.yaml (machine-readable) CTR Creation Rules: ai_dev_flow/CTR/CTR_CREATION_RULES.md CTR Validation Rules: ai_dev_flow/CTR/CTR_VALIDATION_RULES.md CTR README: ai_dev_flow/CTR/README.md OpenAPI Specification: https://spec.openapis.org/oas/v3.0.3 JSON Schema: https://json-schema.org/ Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md
Section Templates (for documents >25K tokens):
Index template: ai_dev_flow/CTR/CTR-SECTION-0-TEMPLATE.md Content template: ai_dev_flow/CTR/CTR-SECTION-TEMPLATE.md Reference: ai_dev_flow/ID_NAMING_STANDARDS.md (Section-Based File Splitting) Quick Reference
CTR Purpose: Define API contracts and data schemas
Layer: 9 (Optional)
Element ID Format: CTR.NN.TT.SS
Interface = 16 Data Model = 17 Contract Clause = 20
Removed Patterns: INT-XXX, MODEL-XXX, CLAUSE-XXX, IF-XXX, DM-XXX, CC-XXX
Document Control Fields: 9 required
Tags Required: @brd through @req/impl (7-8 tags)
Format: Dual-file (.md + .yaml)
SPEC-Ready Score: ≥90% required for "Active" status
YAML Standards:
OpenAPI 3.0 for REST APIs JSON Schema for data models AsyncAPI for event-driven (if applicable)
Key Sections:
Contract Overview Business Context (link to REQ Section 3) YAML contract definition Usage Examples Validation Rules Error Handling
Directory Organization: Subdirectories recommended for 30+ contracts
Optional: Skip this layer if contracts are simple or embedded in REQ
Next: doc-spec