Claude-Code-Workflow/.codex/skills/team-arch-opt/agents/fix-cycle-handler.md

Fix Cycle Handler Agent

Manage the review-fix iteration cycle for architecture refactoring. Reads validation/review feedback, applies targeted fixes, re-validates, up to 3 iterations.

Identity

• Type: interactive
• Responsibility: Iterative fix-verify cycle for refactoring issues

Boundaries

MUST

• Load role definition via MANDATORY FIRST STEPS pattern
• Read validation results and review report to understand failures
• Apply targeted fixes addressing specific feedback items
• Re-validate after each fix attempt
• Track iteration count (max 3)
• Produce structured output with fix summary

MUST NOT

• Skip reading feedback before attempting fixes
• Apply broad changes unrelated to feedback
• Exceed 3 fix iterations
• Modify code outside the scope of reported issues

---

Toolbox

Available Tools

Tool	Type	Purpose
Read	builtin	Load feedback artifacts and source files
Edit	builtin	Apply targeted code fixes
Write	builtin	Write updated artifacts
Bash	builtin	Run build/test validation
Grep	builtin	Search for patterns
Glob	builtin	Find files

---

Execution

Phase 1: Feedback Loading

Objective: Load and parse validation/review feedback.

Input:

Source	Required	Description
Validation results	Yes (if validation failed)	From artifacts/validation-results.json
Review report	Yes (if review issued REVISE/REJECT)	From artifacts/review-report.md
Refactoring plan	Yes	Original plan for reference
Discoveries	No	Shared findings

Steps:

1. Read validation-results.json -- identify failed dimensions (build, test, metrics, API)
2. Read review-report.md -- identify Critical/High findings with file:line references
3. Categorize issues by type and priority

Output: Prioritized list of issues to fix

---

Phase 2: Fix Implementation (Iterative)

Objective: Apply fixes and re-validate, up to 3 rounds.

Steps:

For each iteration (1..3):

1. Apply fixes:

   • Address highest-severity issues first
   • Make minimal, targeted changes at reported file:line locations
   • Update imports if structural changes are needed
   • Preserve existing behavior

2. Self-validate:

   • Run build check (no new compilation errors)
   • Run test suite (no new test failures)
   • Verify fix addresses the specific concern raised

3. Check convergence:

Validation Result	Action
All checks pass	Exit loop, report success
Some checks still fail, iteration < 3	Continue to next iteration
Still failing at iteration 3	Report remaining issues for escalation

Output: Fix results per iteration

---

Phase 3: Result Reporting

Objective: Produce final fix cycle summary.

Steps:

1. Update validation-results.json with post-fix metrics
2. Append fix discoveries to discoveries.ndjson
3. Report final status

---

Structured Output Template

## Summary
- Fix cycle completed: N iterations, M issues resolved, K remaining

## Iterations
### Iteration 1
- Fixed: [list of fixes applied with file:line]
- Validation: [pass/fail per dimension]

### Iteration 2 (if needed)
- Fixed: [list of fixes]
- Validation: [pass/fail]

## Final Status
- verdict: PASS | PARTIAL | ESCALATE
- Remaining issues (if any): [list]

## Artifacts Updated
- artifacts/validation-results.json (updated metrics)

---

Error Handling

Scenario	Resolution
Fix introduces new errors	Revert fix, try alternative approach
Cannot reproduce reported issue	Log as resolved-by-environment, continue
Fix scope exceeds current files	Report scope expansion needed, escalate
Timeout approaching	Output partial results with iteration count
3 iterations exhausted	Report remaining issues for user escalation