name	doc-ctr
description	Create Data Contracts (CTR) - Optional Layer 9 artifact using dual-file format (.md + .yaml) for API/data contracts
tags	sdd-workflow, layer-9-artifact, shared-architecture
custom_fields	[object Object]

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), IPLAN (Layer 12), Code (Layer 13)

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-000_*)

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

Pattern: CTR-000_*.md, CTR-000_*.yaml

Document Types:

Index documents (CTR-000_index.md)
Traceability matrix templates (CTR-000_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-000_* 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

2. 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%)

3. 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

5. 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

6. 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)

8. 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.

9. 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, IPLAN, ICON	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
IPLAN (Layer 12) - Implementation plans
Code (Layer 13) - Implementation

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.

Step 3: Create CTR Files (Dual Format)

Markdown file: ai_dev_flow/CTR/CTR-NN_{slug}.md YAML file: ai_dev_flow/CTR/CTR-NN_{slug}.yaml

Example:

ai_dev_flow/CTR/CTR-01_data_validation.md
ai_dev_flow/CTR/CTR-01_data_validation.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-000_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