doc-ctr-autopilot（文档 CTR 自动驾驶仪）

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)

Input Contract (IPLAN-004 Standard)

• Supported modes:

- --ref <path> - --prompt "<text>" - --iplan <path|IPLAN-NNN>

• Precedence: --iplan > --ref > --prompt
• IPLAN resolution order:

1. Use explicit file path when it exists 2. Resolve work_plans/IPLAN-NNN*.md 3. Resolve governance/plans/IPLAN-NNN*.md 4. If multiple matches exist, fail with disambiguation request

• Merge conflict rule:

- Objective/scope conflicts between primary and supplemental sources are blocking and require user clarification.

Input Contract (IPLAN-004 Standard)

• Supported modes:

- --ref <path> - --prompt "<text>" - --iplan <path|IPLAN-NNN>

• Precedence: --iplan > --ref > --prompt
• IPLAN resolution order:

1. Use explicit file path when it exists 2. Resolve work_plans/IPLAN-NNN*.md 3. Resolve governance/plans/IPLAN-NNN*.md 4. If multiple matches exist, fail with disambiguation request

• Merge conflict rule:

- Objective/scope conflicts between primary and supplemental sources are blocking and require user clarification.

Skill Dependencies

Document Type Contract (MANDATORY)

When generating CTR document instances, the autopilot MUST:

1. Read instance_document_type from template:

- Source: ai_dev_ssd_flow/08_CTR/CTR-MVP-TEMPLATE.yaml - Field: metadata.instance_document_type: "ctr-document"

1. Set document_type in generated document frontmatter: custom_fields: document_type: ctr-document # NOT "template" artifact_type: CTR layer: 8
2. Validation: Generated documents MUST have document_type: ctr-document

- Templates have document_type: template - Instances have document_type: ctr-document - Schema validates both values

Error Handling: If instance_document_type is missing from template, default to ctr-document.

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?

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

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

1. OpenAPI Compliance:

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

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

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

1. 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
2. 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.2501 | ✅ |
| 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.1601 | ✅ |

### 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