doc-ctr-autopilot

Purpose

Automated Data Contracts (CTR) generation pipeline that first analyzes which modules require CTR documents, then processes REQ documents to generate dual-file contracts (markdown + YAML) with SPEC-Ready scoring.

Layer: 8 (Optional layer for API/data contracts)

Upstream: REQ (Layer 7) – Section 3 Interface Specifications, Section 4 Data Schemas

Downstream: SPEC (Layer 9), TSPEC (Layer 10), TASKS (Layer 11)

Skill Dependencies

Smart Document Detection

The autopilot automatically determines the action based on the input document type.

Input Type Recognition

Detection Algorithm

1. Parse input: Extract TYPE and NN from "{TYPE}-{NN}"
2. Determine action:
   - IF TYPE == "CTR": Review Mode
   - ELSE IF TYPE == "REQ": Generate/Find Mode
   - ELSE: Error (invalid type for this autopilot)
3. For Generate/Find Mode:
   - Check: Does CTR-{NN} exist in docs/08_CTR/?
   - IF exists: Switch to Review Mode for CTR-{NN}
   - ELSE: Proceed with Generation from REQ-{NN}

File Existence Check

# Check for nested folder structure (mandatory)
ls docs/08_CTR/CTR-{NN}_*/

Examples

# Review mode (same type - CTR input)
/doc-ctr-autopilot CTR-01           # Reviews existing CTR-01

# Generate/Find mode (upstream type - REQ input)
/doc-ctr-autopilot REQ-01           # Generates CTR-01 if missing, or reviews existing CTR-01

# Multiple inputs
/doc-ctr-autopilot REQ-01,REQ-02    # Generates/reviews CTR-01 and CTR-02
/doc-ctr-autopilot CTR-01,CTR-02    # Reviews CTR-01 and CTR-02

Action Determination Output

Input: REQ-01
├── Detected Type: REQ (upstream)
├── Expected CTR: CTR-01
├── CTR Exists: Yes → docs/08_CTR/CTR-01_f1_iam/
└── Action: REVIEW MODE - Running doc-ctr-reviewer on CTR-01

Input: REQ-05
├── Detected Type: REQ (upstream)
├── Expected CTR: CTR-05
├── CTR Exists: No
└── Action: GENERATE MODE - Creating CTR-05 from REQ-05

Input: CTR-03
├── Detected Type: CTR (self)
└── Action: REVIEW MODE - Running doc-ctr-reviewer on CTR-03

Workflow Overview

flowchart TD
    subgraph Phase0["Phase 0: CTR Requirement Analysis"]
        A0[Start] --> B0[Read All REQ Documents]
        B0 --> C0[Analyze Section 4: Interface Definition]
        C0 --> D0[Check CTR Requirement Criteria]
        D0 --> E0{Has External APIs?}
        E0 -->|Yes| F0[Mark: CTR REQUIRED]
        E0 -->|No| G0[Mark: CTR NOT REQUIRED]
        F0 --> H0[Generate CTR Requirement Matrix]
        G0 --> H0
        H0 --> I0[User Confirmation]
    end

    subgraph Phase1["Phase 1: REQ Analysis"]
        I0 --> A[Filter REQ by CTR Required]
        A --> B[Read CTR-Required REQ Documents]
        B --> C[Extract Section 3: Interface Specifications]
        C --> D[Extract Section 4: Data Schemas]
        D --> E[Identify Contract Candidates]
    end

    subgraph Phase2["Phase 2: CTR Readiness Check"]
        E --> F[Check REQ SPEC-Ready Score]
        F --> G{Score >= 90%?}
        G -->|No| H[Flag REQ Issues]
        H --> I{Auto-Fixable?}
        I -->|Yes| J[Fix REQ Issues]
        J --> F
        I -->|No| K[Abort - Manual Fix Required]
        G -->|Yes| L[Mark REQ Ready]
    end

    subgraph Phase3["Phase 3: CTR Generation"]
        L --> M[Generate CTR-NN.md]
        M --> N[Generate CTR-NN.yaml]
        N --> O[quality-advisor: Real-time Feedback]
        O --> P[Add Traceability Tags]
        P --> Q[Write Dual Files]
    end

    subgraph Phase4["Phase 4: CTR Validation"]
        Q --> R[Run doc-ctr-validator]
        R --> S{SPEC-Ready >= 90%?}
        S -->|No| T[Auto-Fix CTR Issues]
        T --> U[Re-validate CTR]
        U --> S
        S -->|Yes| V[Mark CTR Validated]
    end

    subgraph Phase5["Phase 5: Review & Fix Cycle"]
        V --> W[Run doc-ctr-reviewer]
        W --> W2{Score >= 90?}
        W2 -->|No| W3[Run doc-ctr-fixer]
        W3 --> W4{Iteration < Max?}
        W4 -->|Yes| W
        W4 -->|No| W5[Flag Manual Review]
        W2 -->|Yes| X[Verify Quality Checks]
        W5 --> X
        X --> Y[Update Traceability Matrix]
        Y --> Z[Generate Summary Report]
    end

    Z --> AA[Complete]
    K --> AB[Exit with Error]

Detailed Workflow

Phase 0: CTR Requirement Analysis (MANDATORY FIRST STEP)

Determine which REQ documents require CTR (Data Contracts) generation.

IMPORTANT: Not all modules need CTR documents. CTR is only required for modules with external-facing APIs or contracts.

CTR Requirement Criteria

CTR Requirement Keywords (Detection Patterns)

POSITIVE Indicators (CTR Required):

# REST API patterns
Endpoint:\s*(POST|GET|PUT|DELETE|PATCH)
(POST|GET|PUT|DELETE|PATCH)\s+/api/
/api/v[0-9]+/

# Streaming patterns
SSE|Server-Sent Events
/chat|/stream
EventSource|text/event-stream

# Webhook patterns
/webhooks/
webhook.*configuration
webhook.*endpoint

# Contract patterns
OpenAPI|openapi:
Request:|Response:
Response \(Success\):|Response \(Error\):

NEGATIVE Indicators (CTR NOT Required):

# Internal only
internal only|internal interface|internal use
consumed by|consumer of

# Standard endpoints (no contract needed)
/metrics|/health|/ready|/live

# Infrastructure
infrastructure platform|internal platform
repository pattern|storage layer

# Middleware
middleware|security layer|validation layer

Phase 0 Execution Steps

1. Read All REQ Documents

   # Read docs/07_REQ/REQ-*.md files
   

2. For Each REQ Document, Check:

   • Does Section 4 (Interface Definition) contain HTTP endpoints?
   • Does Section 4.1 (API Contract) define request/response formats?
   • Are there external-facing API surfaces?

3. Generate CTR Requirement Matrix:

## CTR Requirement Analysis Matrix

| REQ ID | Module | Has External API? | Key Indicators | CTR Required? |
|--------|--------|-------------------|----------------|---------------|
| REQ-01 | F1 IAM | ✅ | `POST /api/v1/auth/login`, `POST /api/v1/auth/refresh` | ✅ YES |
| REQ-02 | F2 Session | ✅ | `POST /api/v1/sessions`, session management endpoints | ✅ YES |
| REQ-03 | F3 Observability | ❌ | Only `/metrics` (Prometheus standard) | ❌ NO |
| REQ-04 | F4 SecOps | ❌ | Internal security operations, audit APIs internal | ❌ NO |
| REQ-05 | F5 SelfOps | ❌ | Internal automation, health checks internal | ❌ NO |
| REQ-06 | F6 Infrastructure | ❌ | Internal infrastructure platform | ❌ NO |
| REQ-07 | F7 Config | ❌ | Internal configuration management | ❌ NO |
| REQ-08 | D1 Agent Orch | ✅ | AG-UI SSE `/api/v1/chat`, streaming protocol | ✅ YES |
| REQ-09 | D2 Cost Analytics | ✅ | `/api/v1/costs/*` query endpoints | ✅ YES |
| REQ-10 | D3 User Experience | ❌ | Frontend - consumes APIs, no backend | ❌ NO |
| REQ-11 | D4 Multi-Cloud | ❌ | Internal cloud integration layer | ❌ NO |
| REQ-12 | D5 Data Persistence | ❌ | Internal storage, repository pattern | ❌ NO |
| REQ-13 | D6 REST APIs | ✅ | Primary API gateway, all external endpoints | ✅ YES |
| REQ-14 | D7 Security | ❌ | Internal security middleware | ❌ NO |

4. Present Summary and Request Confirmation:

## Phase 0 Complete: CTR Requirement Analysis

### Modules Requiring CTR (External APIs)

| CTR ID | Source REQ | Module | Key API Surfaces |
|--------|------------|--------|------------------|
| CTR-01 | REQ-01 | F1 IAM | Authentication, token refresh, session APIs |
| CTR-02 | REQ-02 | F2 Session | Session CRUD, context management |
| CTR-08 | REQ-08 | D1 Agent Orch | AG-UI SSE streaming, chat endpoints |
| CTR-09 | REQ-09 | D2 Cost Analytics | Cost query, breakdown, forecast endpoints |
| CTR-13 | REQ-13 | D6 REST APIs | Full API gateway (aggregates all endpoints) |

### Modules NOT Requiring CTR (Internal Only)

| REQ ID | Module | Reason |
|--------|--------|--------|
| REQ-03 | F3 Observability | Prometheus /metrics only (standard format) |
| REQ-04 | F4 SecOps | Internal security operations |
| REQ-05 | F5 SelfOps | Internal automation |
| REQ-06 | F6 Infrastructure | Internal platform |
| REQ-07 | F7 Config | Internal configuration |
| REQ-10 | D3 User Experience | Frontend consumer |
| REQ-11 | D4 Multi-Cloud | Internal integration |
| REQ-12 | D5 Data Persistence | Internal storage |
| REQ-14 | D7 Security | Internal middleware |

### Summary
- **CTR Required**: 5 modules
- **CTR Not Required**: 9 modules
- **Total CTR Documents to Generate**: 5 (dual-file: 10 files total)

Proceed with CTR generation for 5 modules? [Y/n]

Phase 1: REQ Analysis

Extract interface and data schema information from CTR-required REQ documents only.

REQ Sections to Extract:

Phase 2: CTR Readiness Check

Validate that source REQ documents meet quality thresholds.

Validation Criteria:

• REQ SPEC-Ready Score ≥ 90%
• REQ CTR-Ready Score ≥ 90%
• Section 4 (Interface Definition) complete
• Error catalog defined in Section 5

Phase 3: CTR Generation

Generate dual-file contracts for each CTR-required module.

Dual-File Structure (ALWAYS use nested folders):

docs/08_CTR/
├── CTR-01_f1_iam_api/
│   ├── CTR-01_f1_iam_api.md         # Documentation file
│   ├── CTR-01_f1_iam_api.yaml       # OpenAPI specification
│   ├── CTR-01.R_review_report_v001.md
│   ├── CTR-01.F_fix_report_v001.md
│   └── .drift_cache.json
├── CTR-02_f2_session_api/
│   ├── CTR-02_f2_session_api.md
│   └── CTR-02_f2_session_api.yaml
├── CTR-08_d1_agent_api/
│   ├── CTR-08_d1_agent_api.md
│   └── CTR-08_d1_agent_api.yaml
└── ...

Nested Folder Rule: ALL CTRs use nested folders (CTR-NN_{slug}/) regardless of size. This keeps dual files (.md + .yaml) and companion files (review reports, fix reports, drift cache) organized together.

Markdown File Structure (CTR-NN_{slug}.md):

• Document Control
• Contract Overview
• Business Context
• Interface Documentation
• Usage Examples
• Error Handling
• Traceability

YAML File Structure (CTR-NN_{slug}.yaml):

openapi: "3.0.3"
info:
  title: "Contract Title"
  version: "1.0.0"
  description: "Contract description"
  contact:
    name: "API Team"
servers:
  - url: "https://api.example.com/v1"
paths:
  /api/v1/resource:
    get:
      operationId: getResource
      summary: "Get resource"
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceModel'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ResourceModel:
      type: object
      properties: {}
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'

Cumulative Tags (7 Required)

@brd: BRD-NN
@prd: PRD-NN
@ears: EARS-NN
@bdd: BDD-NN
@adr: ADR-NN
@sys: SYS-NN
@req: REQ-NN

Phase 4: CTR Validation

Run doc-ctr-validator on each generated CTR document.

Validation Criteria:

• SPEC-Ready Score ≥ 90%
• OpenAPI schema valid
• All endpoints documented
• Error responses complete
• Security schemes defined

Phase 5: Review & Fix Cycle (v2.3)

Iterative review and fix cycle to ensure CTR quality before completion.

flowchart TD
    A[Phase 5 Start] --> B[Run doc-ctr-reviewer]
    B --> C[Generate Review Report]
    C --> D{Review Score >= 90?}

    D -->|Yes| E[PASS - Proceed to Phase 6]
    D -->|No| F{Iteration < Max?}

    F -->|Yes| G[Run doc-ctr-fixer]
    G --> H[Apply Fixes]
    H --> I[Generate Fix Report]
    I --> J[Increment Iteration]
    J --> B

    F -->|No| K[Flag for Manual Review]
    K --> L[Generate Final Report with Remaining Issues]
    L --> E

5.1 Initial Review

Run doc-ctr-reviewer to identify issues.

/doc-ctr-reviewer CTR-NN

Output: CTR-NN.R_review_report_v001.md

5.2 Fix Cycle

If review score < 90%, invoke doc-ctr-fixer.

/doc-ctr-fixer CTR-NN --revalidate

Fix Categories:

Output: CTR-NN.F_fix_report_v001.md

5.3 Re-Review

After fixes, automatically re-run reviewer.

/doc-ctr-reviewer CTR-NN

Output: CTR-NN.R_review_report_v002.md

5.4 Iteration Control

Iteration Example:

Iteration 1:
  Review v001: Score 85 (2 errors, 4 warnings)
  Fix v001: Fixed 5 issues, created 1 file

Iteration 2:
  Review v002: Score 94 (0 errors, 2 warnings)
  Status: PASS (score >= 90)

5.5 Quality Checks (Post-Fix)

After passing the fix cycle:

1. Dual-File Consistency:

   • MD and YAML files synchronized
   • All endpoints documented in both files
   • Schema definitions match

2. OpenAPI Compliance:

   • Valid OpenAPI 3.0.3 schema
   • All operations have operationId
   • Error responses complete (401, 403, 500)

3. Element ID Compliance (per doc-naming skill):

   • All IDs use CTR.NN.TT.SS format
   • Element type codes valid for CTR (16, 17, 20)
   • No legacy patterns (IF-XXX, DM-XXX, CC-XXX)

4. SPEC-Ready Report:

   SPEC-Ready Score Breakdown
   =========================
   OpenAPI Validity:       25/25
   Schema Completeness:    18/20
   Error Responses:        15/15
   Security Schemes:       15/15
   Dual-File Consistency:  10/10
   Traceability (7 tags):  10/10
   Element IDs:            5/5
   ----------------------------
   Total SPEC-Ready Score: 98/100 (Target: >= 90)
   Status: READY FOR SPEC GENERATION
   

5. Traceability Matrix Update:

   # Update CTR traceability
   python ai_dev_flow/scripts/update_traceability_matrix.py \
     --ctr docs/08_CTR/CTR-NN_{slug}.md \
     --matrix docs/08_CTR/CTR-00_TRACEABILITY_MATRIX.md
   

Element Type Codes

Configuration

Default Configuration

ctr_autopilot:
  version: "2.0"

  phase0:
    enabled: true  # Always analyze CTR requirements first
    user_confirmation: true  # Pause for user approval

  scoring:
    spec_ready_min: 90
    ctr_ready_min: 90
    strict_mode: false

  execution:
    max_parallel: 3        # HARD LIMIT - do not exceed
    chunk_size: 3          # Documents per chunk
    pause_between_chunks: true
    auto_fix: true
    continue_on_error: false
    timeout_per_req: 180  # seconds

  output:
    dual_file: true  # md + yaml
    report_format: markdown

  validation:
    skip_validation: false
    fix_iterations_max: 3

Context Management

Chunked Parallel Execution (MANDATORY)

CRITICAL: To prevent conversation context overflow errors (“Prompt is too long”, “Conversation too long”), all autopilot operations MUST follow chunked execution rules:

Chunk Size Limit: Maximum 3 documents per chunk

Chunking Rules:

1. Chunk Formation: Group CTR-required modules into chunks of maximum 3 at a time
2. Sequential Chunk Processing: Process one chunk at a time, completing all documents in a chunk before starting the next
3. Context Pause: After completing each chunk, provide a summary and pause for user acknowledgment
4. Progress Tracking: Display chunk progress (e.g., “Chunk 2/2: Processing CTR-08, CTR-09, CTR-13…”)

Why Chunking is Required:

• Prevents “Conversation too long” errors during batch processing
• Allows context compaction between chunks
• Enables recovery from failures without losing all progress
• Provides natural checkpoints for user review

Chunk Completion Template:

## Chunk N/M Complete

Generated:
- CTR-XX: SPEC-Ready Score 94% (md + yaml)
- CTR-YY: SPEC-Ready Score 92% (md + yaml)
- CTR-ZZ: SPEC-Ready Score 95% (md + yaml)

Proceeding to next chunk...

Command Usage

Analyze CTR Requirements Only

/doc-ctr-autopilot --analyze

Runs Phase 0 only, outputs CTR Requirement Matrix without generating files.

Generate CTR for Specific Modules

/doc-ctr-autopilot REQ-01 REQ-13

Generates CTR for specified REQ documents (skips Phase 0 analysis for these).

Generate All Required CTR

/doc-ctr-autopilot --all

Runs full workflow: Phase 0 analysis → user confirmation → generate all CTR-required modules.

Skip Phase 0 (Force Generate)

/doc-ctr-autopilot --all --skip-analysis

Skip Phase 0 and generate CTR for ALL REQ documents (not recommended).

Dry Run Mode

/doc-ctr-autopilot --all --dry-run

Preview execution plan without generating or modifying files.

Review Mode

Validate existing CTR documents and generate quality reports without modification.

Review Mode Command

/doc-ctr-autopilot --review docs/08_CTR/

Review Mode Process

flowchart TD
    A[Start Review] --> B[Scan CTR Directory]
    B --> C[Identify Dual-File Pairs]
    C --> D{For Each Pair}
    D --> E[Validate MD Structure]
    E --> F[Validate YAML/OpenAPI]
    F --> G[Check Consistency]
    G --> H[Calculate SPEC-Ready]
    H --> I[Categorize Issues]
    I --> J{More Pairs?}
    J -->|Yes| D
    J -->|No| K[Generate Report]
    K --> L[Complete]

Review Mode Output

No files modified – Read-only analysis with detailed report.

Review Report Template

## CTR Review Report

**Generated**: YYYY-MM-DD HH:MM:SS
**Mode**: Review (Read-Only)
**Scope**: docs/08_CTR/

### Document Summary

| CTR ID | Module | MD | YAML | Consistency | SPEC-Ready | Status |
|--------|--------|---|----|-------------|------------|--------|
| CTR-01 | F1 IAM | ✅ | ✅ | ✅ | 94% ✅ | Passed |
| CTR-02 | F2 Session | ✅ | 🟡 | 🟡 | 87% 🟡 | Needs Review |
| CTR-08 | D1 Agent | ✅ | ❌ | ❌ | 72% ❌ | Failed |
| CTR-09 | D2 Cost | ✅ | ✅ | ✅ | 92% ✅ | Passed |
| CTR-13 | D6 Gateway | ✅ | ✅ | ✅ | 95% ✅ | Passed |

### Score Breakdown (Aggregate)

| Component | Weight | Score | Status |
|-----------|--------|-------|--------|
| OpenAPI Validity | 25% | 23/25 | ✅ |
| Schema Completeness | 20% | 18/20 | ✅ |
| Error Responses | 15% | 12/15 | 🟡 |
| Security Schemes | 15% | 15/15 | ✅ |
| Dual-File Consistency | 10% | 8/10 | 🟡 |
| Traceability (7 tags) | 10% | 9/10 | ✅ |
| Element IDs | 5% | 5/5 | ✅ |
| **Total** | **100%** | **90/100** | **✅** |

### Issues Detected

#### Auto-Fixable Issues
| CTR | Issue | Fix Action |
|-----|-------|------------|
| CTR-02 | Missing @ears tag | Add placeholder reference |
| CTR-02 | YAML schema $ref mismatch | Sync with MD definitions |
| CTR-08 | Invalid OpenAPI operationId | Generate from path |
| CTR-08 | Missing 401 response | Add from error template |

#### Manual Review Required
| CTR | Issue | Reason |
|-----|-------|--------|
| CTR-08 | Incomplete streaming spec | Business logic unclear |
| CTR-08 | Missing SSE event types | Requires domain knowledge |

### Recommendations

1. Run Fix Mode to auto-repair 4 issues
2. Manual review needed for CTR-08 streaming specification
3. Consider regenerating CTR-08 from REQ-08

### Fix Mode Command

To auto-fix detected issues:
\`\`\`bash
/doc-ctr-autopilot --fix docs/08_CTR/
\`\`\`

Review Configuration

review_mode:
  enabled: true
  scope: directory  # single, directory, all
  report_output: tmp/ctr_review_report.md
  checks:
    openapi_validation: true
    schema_completeness: true
    error_responses: true
    security_schemes: true
    dual_file_consistency: true
    traceability: true
    element_ids: true
  thresholds:
    pass: 90
    warning: 85
    fail: 0

Review Command Options

Fix Mode

Auto-repair existing CTR documents while preserving manually-created content.

Fix Mode Command

/doc-ctr-autopilot --fix docs/08_CTR/

Fix Mode Process

flowchart TD
    A[Start Fix] --> B[Run Review First]
    B --> C[Identify Fixable Issues]
    C --> D[Create Backups]
    D --> E{For Each Issue}
    E --> F{Issue Type?}
    F -->|openapi| G[Fix OpenAPI Schema]
    F -->|consistency| H[Sync MD ↔ YAML]
    F -->|element_ids| I[Migrate Legacy IDs]
    F -->|traceability| J[Add Missing Tags]
    F -->|sections| K[Add Missing Sections]
    F -->|responses| L[Add Error Responses]
    G --> M[Apply Fix]
    H --> M
    I --> M
    J --> M
    K --> M
    L --> M
    M --> N{More Issues?}
    N -->|Yes| E
    N -->|No| O[Re-validate]
    O --> P[Generate Fix Report]
    P --> Q[Complete]

Fix Categories

Content Preservation Rules

NEVER Modified:

• Manually written endpoint descriptions
• Custom schema properties
• Business-specific error messages
• Existing operationIds (unless invalid)
• Custom security scheme configurations
• API versioning in paths

Always Preserved:

• Existing endpoint definitions
• Custom schema validators
• Response examples
• Manually added headers
• Custom component definitions

Element ID Migration

Legacy patterns are converted to unified format:

Dual-File Consistency Fixes

OpenAPI Auto-Fixes

Fix Report Template

## CTR Fix Report

**Generated**: YYYY-MM-DD HH:MM:SS
**Mode**: Fix (Auto-Repair)
**Scope**: docs/08_CTR/

### Backup Created
Location: `tmp/ctr_backup_YYYYMMDD_HHMMSS/`

### Fixes Applied

| CTR | Category | Issue | Fix Applied | Result |
|-----|----------|-------|-------------|--------|
| CTR-02 | traceability | Missing @ears | Added @ears: EARS.02.25.01 | ✅ |
| CTR-02 | consistency | Schema mismatch | Synced SessionModel | ✅ |
| CTR-08 | openapi | Missing operationId | Added getChatStream | ✅ |
| CTR-08 | responses | Missing 401 | Added Unauthorized | ✅ |
| CTR-08 | element_ids | IF-001 format | → CTR.08.16.01 | ✅ |

### Before/After Scores

| CTR | Before | After | Change |
|-----|--------|-------|--------|
| CTR-02 | 87% | 94% | +7% ✅ |
| CTR-08 | 72% | 91% | +19% ✅ |

### Issues Requiring Manual Review

| CTR | Issue | Reason |
|-----|-------|--------|
| CTR-08 | SSE event type definitions | Requires business input |
| CTR-08 | Streaming protocol details | Domain-specific |

### Summary
- **Total Issues Detected**: 7
- **Auto-Fixed**: 5
- **Manual Review Required**: 2
- **Documents Modified**: 2 (CTR-02, CTR-08)
- **Documents Unchanged**: 3 (passed validation)

Fix Configuration

fix_mode:
  enabled: true
  create_backup: true  # Always backup before fix
  backup_location: tmp/ctr_backup_{timestamp}/
  categories:
    openapi: true
    consistency: true
    element_ids: true
    traceability: true
    sections: true
    responses: true
    security: false  # Requires review - medium risk
    paths: false     # Requires review - medium risk
  max_iterations: 3
  dry_run: false
  preserve_content: true

Fix Command Options

Fix Mode Examples

# Fix all auto-fixable issues
/doc-ctr-autopilot --fix docs/08_CTR/

# Fix specific CTR document
/doc-ctr-autopilot --fix docs/08_CTR/CTR-08_d1_agent_api.md

# Preview fixes without applying
/doc-ctr-autopilot --fix docs/08_CTR/ --dry-run

# Fix only OpenAPI issues
/doc-ctr-autopilot --fix docs/08_CTR/ --category openapi

# Fix with force (includes medium-risk fixes)
/doc-ctr-autopilot --fix docs/08_CTR/ --force

# Fix and regenerate if needed
/doc-ctr-autopilot --fix docs/08_CTR/ --regenerate-on-fail

Related Resources

• CTR Skill: .claude/skills/doc-ctr/SKILL.md
• CTR Validator: .claude/skills/doc-ctr-validator/SKILL.md
• Naming Standards: .claude/skills/doc-naming/SKILL.md
• Quality Advisor: .claude/skills/quality-advisor/SKILL.md
• CTR Template: ai_dev_ssd_flow/08_CTR/CTR-MVP-TEMPLATE.md

Review Document Standards (v2.2)

Review reports generated by this skill are formal project documents and MUST comply with shared standards.

Reference: See REVIEW_DOCUMENT_STANDARDS.md in the skills directory for complete requirements.

Key Requirements:

1. Storage Location: Same folder as the reviewed CTR document
2. File Naming: CTR-NN.R_review_report.md
3. YAML Frontmatter: Required with artifact_type: CTR-REVIEW, layer: 8
4. Score Field: spec_ready_score_claimed / spec_ready_score_validated
5. Parent Reference: Must link to parent CTR document

Example Location:

docs/08_CTR/CTR-03-001_provider_api/
├── CTR-03-001.md
├── CTR-03-001.yaml
└── CTR-03-001.R_review_report.md    # ← Review stored here

Version History