doc-cspec-fixer

Purpose

Automated fix skill that reads the latest review report and applies fixes to CSPEC (Code Specification) documents. This skill bridges the gap between doc-cspec-reviewer (which identifies issues) and the corrected CSPEC, enabling iterative improvement cycles.

Layer: 9.50 (CSPEC Quality Improvement)

Upstream: REQ, CTR, CSPEC, Review Report (CSPEC-NN.A_audit_report_vNNN.md)

Downstream: Fixed CSPEC, Fix Report (CSPEC-NN.F_fix_report_vNNN.md)

---

When to Use

Use doc-cspec-fixer when:

• After Review: Run after doc-cspec-reviewer identifies issues
• Iterative Improvement: Part of Review → Fix → Review cycle
• CTR Alignment: Fix CTR compliance issues
• YAML Structure Issues: CSPEC contains malformed YAML blocks

Do NOT use when:

• No review report exists (run doc-cspec-reviewer first)
• Issues require manual architectural decisions
• CTR contract itself needs modification

---

Fixable Issue Types

Automatic Fixes

Issue Type	Fix Action
Missing document_type	Add document_type: cspec-document
Missing subtype_code	Add subtype_code: 50
Broken internal links	Update to correct paths
Missing traceability tags	Add required cumulative tags
YAML syntax errors	Fix formatting issues
Incomplete metadata	Add required fields

Semi-Automatic Fixes (Require Confirmation)

Issue Type	Fix Action
Missing interface definitions	Generate skeleton from CTR
Incomplete test mapping	Generate test case placeholders
Missing algorithm details	Add TODO markers

Manual Review Required

Issue Type	Action
Architectural changes	Flag for human review
CTR contract mismatches	Escalate to CTR owner
Business logic errors	Requires domain expertise

---

Execution Flow

flowchart TD
    A[Read Audit Report] --> B{Issues Found?}
    B -->|No| C[No Action Needed]
    B -->|Yes| D[Categorize Issues]
    D --> E[Apply Auto-Fixes]
    E --> F[Generate Fix Report]
    F --> G[Re-validate]
    G --> H{All Fixed?}
    H -->|Yes| I[Complete]
    H -->|No| J[Flag Manual Issues]

---

Fix Report Format

# CSPEC-NN Fix Report

## Summary
- **Document**: CSPEC-NN_{slug}
- **Fix Date**: YYYY-MM-DD
- **Source Report**: CSPEC-NN.A_audit_report_v001.md
- **Issues Fixed**: N
- **Issues Remaining**: N

## Fixes Applied

### Fix 1: [Issue Title]
- **Type**: [Auto/Semi-Auto]
- **Location**: [section/path]
- **Before**: [old value]
- **After**: [new value]

## Remaining Issues

### Issue 1: [Issue Title]
- **Reason**: Requires manual review
- **Recommendation**: [action needed]

## Validation
- **Post-Fix CODE-Ready Score**: NN%
- **Status**: PASS/FAIL

---

Output Files

File	Purpose
Updated CSPEC YAML	Fixed document
CSPEC-NN.F_fix_report_vNNN.md	Fix report documenting changes

---

Integration

With Reviewer

doc-cspec-reviewer → CSPEC-NN.A_audit_report.md → doc-cspec-fixer → Fixed CSPEC

Iterative Loop

CSPEC → reviewer → audit_report → fixer → fixed_CSPEC → reviewer → ...

Maximum iterations: 3 (to prevent infinite loops)

---

References

• Template: ai_dev_ssd_flow/09_SPEC/CSPEC/CSPEC-MVP-TEMPLATE.yaml
• Schema: ai_dev_ssd_flow/09_SPEC/CSPEC/CSPEC_MVP_SCHEMA.yaml
• Validation Rules: ai_dev_ssd_flow/09_SPEC/CSPEC/CSPEC_MVP_VALIDATION_RULES.md