Claude-Code-Workflow/.codex/skills/spec-generator/phases/06-5-auto-fix.md

Phase 6.5: Auto-Fix

Execution Mode: Agent Delegated This phase is executed by a doc-generator agent when triggered by the orchestrator after Phase 6 identifies issues. The agent reads this file for instructions, applies fixes to affected documents, and returns a JSON summary.

Automatically repair specification issues identified in Phase 6 Readiness Check.

Objective

• Parse readiness-report.md to extract Error and Warning items
• Group issues by originating Phase (2-5)
• Re-generate affected sections with error context injected into CLI prompts
• Re-run Phase 6 validation after fixes

Input

• Dependency: {workDir}/readiness-report.md (Phase 6 output)
• Config: {workDir}/spec-config.json (with iteration_count)
• All Phase 2-5 outputs

Execution Steps

Step 1: Parse Readiness Report

const readinessReport = Read(`${workDir}/readiness-report.md`);
const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));

// Load glossary for terminology consistency during fixes
let glossary = null;
try {
  glossary = JSON.parse(Read(`${workDir}/glossary.json`));
} catch (e) { /* proceed without */ }

// Extract issues from readiness report
// Parse Error and Warning severity items
// Group by originating phase:
//   Phase 2 issues: vision, problem statement, scope, personas
//   Phase 3 issues: requirements, acceptance criteria, priority, traceability
//   Phase 4 issues: architecture, ADRs, tech stack, data model, state machine
//   Phase 5 issues: epics, stories, dependencies, MVP scope

const issuesByPhase = {
  2: [], // product brief issues
  3: [], // requirements issues
  4: [], // architecture issues
  5: []  // epics issues
};

// Parse structured issues from report
// Each issue: { severity: "Error"|"Warning", description: "...", location: "file:section" }

// Map phase numbers to output files
const phaseOutputFile = {
  2: 'product-brief.md',
  3: 'requirements/_index.md',
  4: 'architecture/_index.md',
  5: 'epics/_index.md'
};

Step 2: Fix Affected Phases (Sequential)

For each phase with issues (in order 2 -> 3 -> 4 -> 5):

for (const [phase, issues] of Object.entries(issuesByPhase)) {
  if (issues.length === 0) continue;

  const errorContext = issues.map(i => `[${i.severity}] ${i.description} (at ${i.location})`).join('\n');

  // Read current phase output
  const currentOutput = Read(`${workDir}/${phaseOutputFile[phase]}`);

  Bash({
    command: `ccw cli -p "PURPOSE: Fix specification issues identified in readiness check for Phase ${phase}.
Success: All listed issues resolved while maintaining consistency with other documents.

CURRENT DOCUMENT:
${currentOutput.slice(0, 5000)}

ISSUES TO FIX:
${errorContext}

${glossary ? `GLOSSARY (maintain consistency):
${JSON.stringify(glossary.terms, null, 2)}` : ''}

TASK:
- Address each listed issue specifically
- Maintain all existing content that is not flagged
- Ensure terminology consistency with glossary
- Preserve YAML frontmatter and cross-references
- Use RFC 2119 keywords for behavioral requirements
- Increment document version number

MODE: analysis
EXPECTED: Corrected document content addressing all listed issues
CONSTRAINTS: Minimal changes - only fix flagged issues, do not restructure unflagged sections
" --tool gemini --mode analysis`,
    run_in_background: true
  });

  // Wait for result, apply fixes to document
  // Update document version in frontmatter
}

Step 3: Update State

specConfig.phasesCompleted.push({
  phase: 6.5,
  name: "auto-fix",
  iteration: specConfig.iteration_count,
  phases_fixed: Object.keys(issuesByPhase).filter(p => issuesByPhase[p].length > 0),
  completed_at: new Date().toISOString()
});
Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));

Step 4: Re-run Phase 6 Validation

// Re-execute Phase 6: Readiness Check
// This creates a new readiness-report.md
// If still Fail and iteration_count < 2: loop back to Step 1
// If Pass or iteration_count >= 2: proceed to handoff

Output

• Updated: Phase 2-5 documents (only affected ones)
• Updated: spec-config.json (iteration tracking)
• Triggers: Phase 6 re-validation

Quality Checklist

• All Error-severity issues addressed
• Warning-severity issues attempted (best effort)
• Document versions incremented for modified files
• Terminology consistency maintained
• Cross-references still valid after fixes
• Iteration count not exceeded (max 2)

Next Phase

Re-run Phase 6: Readiness Check to validate fixes.

---

Agent Return Summary

When executed as a delegated agent, return the following JSON summary to the orchestrator:

{
  "phase": 6.5,
  "status": "complete",
  "files_modified": ["list of files that were updated"],
  "issues_fixed": {
    "errors": 0,
    "warnings": 0
  },
  "quality_notes": ["list of fix decisions and remaining concerns"],
  "phases_touched": [2, 3, 4, 5]
}

The orchestrator will:

1. Validate that listed files were actually modified (check version increment)
2. Update spec-config.json iteration tracking
3. Re-trigger Phase 6 validation