Ibrahim-3d/loop-fixer

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:

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

## 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 5 fix cycles — if still failing after 5 rounds, mark track as completed-with-warnings (NEVER ask 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

{
  "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

{
  "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)

{
  "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 >= 5: Mark track as completed-with-warnings — NEVER ask user
• On limit reached:

{
  "loop_state": {
    "current_step": "COMPLETE",
    "step_status": "PASSED_WITH_WARNINGS",
    "checkpoints": {
      "FIX": {
        "status": "COMPLETED_WITH_WARNINGS"
      }
    }
  },
  "warnings": [{
    "id": "warning-1",
    "description": "Fix cycle limit exceeded (5 cycles)",
    "logged_at": "[timestamp]",
    "unresolved_issues": ["list of remaining failures"]
  }]
}

Update Protocol

1. read_file current metadata.json
2. Check fix_cycle_count — if >= 5, complete with warnings (NEVER ask 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