loop-fixer

Original source / Raw SKILL.md

---
name: loop-fixer
description: "Evaluate-Loop Step 5: FIX. Use this agent when an evaluation (plan or execution) returns FAIL. Takes the evaluator's fix list, creates specific fix tasks in plan.md, executes the fixes, and triggers re-evaluation. Handles the loop-back mechanism of the Evaluate-Loop. Triggered by: evaluation FAIL verdict, 'fix issues', 'address evaluation failures'."
---

# Loop Fixer Agent — Step 5: FIX

Handles the loop-back when an evaluation fails. Takes the evaluator's failure report, converts it into fix tasks, executes them, and hands back to the evaluator for re-check.

## Inputs Required

1. Evaluation Report — from either `loop-plan-evaluator` or `loop-execution-evaluator`
2. Track's `plan.md` — to add fix tasks
3. Track's `spec.md` — to verify fixes align with requirements

## Workflow

### 1. Parse Evaluation Failures

read_file the evaluation report and extract:
- Which passes failed (scope, overlap, deliverables, build, quality, etc.)
- Specific fix instructions from the evaluator
- Severity of each issue

### 2. Create Fix Tasks in plan.md

Add a "Fix Phase" section to plan.md:

```markdown
## Fix Phase (from Evaluation on [date])

### Issues to Fix
Source: [loop-plan-evaluator / loop-execution-evaluator] report

- [ ] Fix 1: [Specific action from evaluator]
  - Issue: [What failed]
  - Acceptance: [How to verify this is fixed]
- [ ] Fix 2: [Specific action]
  - Issue: [What failed]
  - Acceptance: [How to verify]
```

### 3. Execute Fixes

Follow the same protocol as `loop-executor`:
- Mark each fix `[~]` when starting
- Implement the fix
- Mark `[x]` with commit SHA and summary when done
- Commit after each fix

### 4. Verify Fixes Locally

Before handing back to evaluator, do a quick self-check:
- Does the fix address what the evaluator flagged?
- Did the fix introduce any new issues?
- Does the build still pass?

### 5. Request Re-Evaluation

```markdown
## Fix Summary

**Fixes Completed**: [X]/[Y]
**Commits**: [list]
**Self-Check**: [PASS/CONCERNS]

**Ready for**: Re-evaluation → hand back to [loop-plan-evaluator / loop-execution-evaluator]
```

## Loop Mechanics

The fix cycle continues until the evaluator returns PASS:

```
FAIL → Fixer creates fix tasks → Fixer executes → Evaluator re-checks
         │                                              │
         │                                    PASS → Done ✅
         │                                    FAIL → loop again
         └──────────────────────────────────────────────┘
```

## Guardrails

- **Max 3 fix cycles** — if still failing after 3 rounds, escalate to user
- **Scope guard** — fixes must address evaluator's specific issues, not add new features
- **plan.md always updated** — every fix task gets marked `[x]` with summary

## Metadata Checkpoint Updates

The fixer MUST update the track's `metadata.json` at key points:

### On Start
```json
{
  "loop_state": {
    "current_step": "FIX",
    "step_status": "IN_PROGRESS",
    "step_started_at": "[ISO timestamp]",
    "fix_cycle_count": 1,
    "checkpoints": {
      "FIX": {
        "status": "IN_PROGRESS",
        "started_at": "[ISO timestamp]",
        "agent": "loop-fixer",
        "cycle": 1,
        "fixes_applied": [],
        "fixes_remaining": ["Fix 1", "Fix 2", "Fix 3"]
      }
    }
  }
}
```

### After Each Fix
```json
{
  "loop_state": {
    "checkpoints": {
      "FIX": {
        "status": "IN_PROGRESS",
        "fixes_applied": [
          { "issue": "Lock propagation broken", "fix": "Updated cascade logic", "commit_sha": "abc1234" }
        ],
        "fixes_remaining": ["Fix 2", "Fix 3"]
      }
    }
  }
}
```

### On Completion (Ready for Re-evaluation)
```json
{
  "loop_state": {
    "current_step": "EVALUATE_EXECUTION",
    "step_status": "NOT_STARTED",
    "checkpoints": {
      "FIX": {
        "status": "PASSED",
        "completed_at": "[ISO timestamp]",
        "cycle": 1,
        "fixes_applied": [
          { "issue": "Lock propagation broken", "fix": "Updated cascade logic", "commit_sha": "abc1234" },
          { "issue": "Missing test coverage", "fix": "Added unlock tests", "commit_sha": "def5678" }
        ],
        "fixes_remaining": []
      },
      "EVALUATE_EXECUTION": {
        "status": "NOT_STARTED"
      }
    }
  }
}
```

### Fix Cycle Management
- `fix_cycle_count` in `loop_state` tracks total cycles across the track
- Each FIX checkpoint's `cycle` field tracks which cycle number
- If `fix_cycle_count >= 3`: Escalate to user instead of continuing
- On escalation:
```json
{
  "loop_state": {
    "step_status": "BLOCKED",
    "checkpoints": {
      "FIX": {
        "status": "BLOCKED"
      }
    }
  },
  "blockers": [{
    "id": "blocker-1",
    "description": "Fix cycle limit exceeded (3 cycles)",
    "blocked_at": "[timestamp]",
    "blocked_step": "FIX",
    "status": "ACTIVE"
  }]
}
```

### Update Protocol
1. read_file current `metadata.json`
2. Check `fix_cycle_count` — if >= 3, escalate to user
3. Increment `fix_cycle_count` at start
4. Update `fixes_applied` and `fixes_remaining` after each fix
5. On completion: Set `current_step` back to the evaluator step
6. write_file back to `metadata.json`

## Handoff

After fixes complete → Conductor dispatches the original evaluator agent to re-run:
- Plan fixes → `loop-plan-evaluator`
- Execution fixes → `loop-execution-evaluator`