agent-remediate-loop

You are running the agent-remediate-loop pipeline.

Agent Roles

Agent	Role in this skill
Claude Code	Orchestrates — reads backlog, routes items, parses verdicts, writes state
Codex	Implements fixes — receives compact task specs, returns diffs
Gemini	Evaluates fixes — reads changed files, returns RESOLVED or NEEDS MORE WORK

LLM Handoff Optimization

Codex

Codex performs best with surgical, unambiguous specs. Prompt format:

Fix: <title>
Location: <file:line>
Problem: <one sentence>
Fix: <one sentence concrete action>
Requirements:
- Implement exactly the fix described. No scope creep.
- Do not add comments.
- Keep changes minimal and surgical.
- Run existing tests for the affected file. Report pass/fail count only.

Failure modes to avoid:

• Prose descriptions without file:line → Codex hallucinates locations
• Multiple fixes in one prompt → Codex picks one and ignores others
• "Refactor" or "improve" language → Codex over-engineers
• Asking Codex to evaluate its own work → always optimistic

Gemini

Gemini performs best with explicit read instructions and a structured verdict format. Prompt structure: (1) read directive, (2) context, (3) verdict format, (4) follow-up instruction.

Read: <file:line>
Context: [severity, original problem, required fix, Codex output summary]
Verdict on line 1: "RESOLVED" or "NEEDS MORE WORK"
If NEEDS MORE WORK: end with "CODEX INSTRUCTIONS:" block — compact re-spec of what still needs to change.

Do NOT specify a Gemini model — let the MCP bridge choose best available. Gemini's large context window is its edge here: it can re-read the changed file in full and compare against the original problem statement without truncation risk.

---

Step 0 — Determine Target File

User may pass a file argument:

• /agent-remediate-loop open-issues.md → .planning/open-issues.md
• /agent-remediate-loop tech-debt.md → .planning/tech-debt.md
• /agent-remediate-loop (no arg) → prompt: "Which file? open-issues.md / tech-debt.md / other?"

Resolve to absolute path under .planning/. If file is outside .planning/, confirm before proceeding.

Set TARGET_FILE = resolved path. Set TARGET_LABEL = filename without extension.

Fingerprint filter (agent-review-loop auto-dispatch):

If invoked with fingerprints: [<slug1>, <slug2>, ...] at invocation start, set FINGERPRINT_FILTER = that list. Step 1 loads only items whose **Fingerprint** matches an entry. All other steps unchanged.

If no fingerprint filter: process all active items in TARGET_FILE.

---

Workflow Overview

TARGET_FILE → [pick item] → Codex fix → Gemini eval → resolved? → archive
                                ↑                ↓ needs more work
                                └────────────────┘

---

Step 1 — Load Items

Read TARGET_FILE. Extract all items — each is a ## SEVERITY: Title block ending at ---. For each block extract:

• **Location** value
• **Fingerprint** value (empty string if absent)
• **Issue** value
• **Fix** value
• **Run** value

Skip already-archived entries (no Location/Issue/Fix, or marked resolved).

If FINGERPRINT_FILTER set: retain only items matching filter. Leave others untouched.

If no active items after filter: report "No active items in TARGET_FILE." and stop.

---

Step 2 — Prioritize

Process order: CRITICAL → HIGH → MEDIUM → LOW. Within tier: top-to-bottom.

---

Step 3 — Codex Fix

For each item:

codex exec --dangerously-bypass-approvals-and-sandbox - <<'EOF'
Fix: <Item Title>
Source file: <TARGET_FILE>
Severity: <CRITICAL|HIGH|MEDIUM|LOW>
Location: <file:line>
Problem: <verbatim Issue text>
Fix: <verbatim Fix text>

Requirements:
- Implement exactly the fix described. No scope creep.
- Do not add comments explaining what you changed.
- Keep changes minimal and surgical.
- Run existing tests if they exist for the affected file. Report pass/fail count only.
EOF

Wait for Codex to complete. Capture result.

---

Step 4 — Gemini Evaluation

After Codex completes:

mcp__agent-bridge__call_gemini(
  prompt="""You are a senior code reviewer evaluating a fix.

Source backlog: <TARGET_LABEL>
Item: <Item Title>
Severity: <CRITICAL|HIGH|MEDIUM|LOW>
Location: <file:line>
Original problem: <verbatim Issue text>
Required fix: <verbatim Fix text>

Codex output:
<paste Codex result>

Your task:
1. Read the relevant changed files at the locations specified.
2. Verify the fix correctly addresses the stated problem.
3. Check for regressions or incomplete implementation.
4. Return a verdict on the FIRST LINE:
   - "RESOLVED" — fix is correct, complete, no regressions.
   - "NEEDS MORE WORK" — fix is incomplete, incorrect, or introduces regressions.
5. Follow verdict with 2-5 bullet points explaining reasoning.
6. If NEEDS MORE WORK, end with a "CODEX INSTRUCTIONS:" block — compact re-spec of exactly what still needs to change (file:line, what, why).

Be strict. A partial fix that leaves the problem open is NEEDS MORE WORK.""",
  cwd="<project_root>"
)

---

Step 5 — Verdict Routing

Parse first line of Gemini response:

RESOLVED:

• Remove item block from TARGET_FILE (match by fingerprint, fall back to title).
• Append to .planning/archive/<TARGET_LABEL>-resolved.md (create if absent):

  ## <Item Title> — Resolved <YYYY-MM-DD>
  **Severity:** <severity>
  **Location:** <file:line>
  **Fingerprint:** <fingerprint or "none">
  **Fix:** <verbatim fix description>
  **Gemini verdict:** <Gemini's reasoning bullets>
  ---
  

• Report: "✓ — resolved and archived."
• Proceed to next item.

NEEDS MORE WORK:

• Extract "CODEX INSTRUCTIONS:" block from Gemini response.
• Re-send to Codex with updated spec (same Step 3 format, replace Fix with CODEX INSTRUCTIONS block).
• Return to Step 4 with new Codex output.
• Repeat until RESOLVED. No iteration cap.

Ambiguous (no clear verdict on line 1): treat as NEEDS MORE WORK.

---

Step 6 — Update TARGET_FILE

After all items resolved:

• If all sections empty, replace active content with:

  # <Original File Title>
  
  _Last updated: <YYYY-MM-DD>. All items resolved and archived._
  
  No active items.
  

---

Step 7 — Update active-context.md

Update relevant line to reflect resolved count, date, and any items requiring multiple Codex iterations.

---

Reporting

Per-item:

[1/N] Working: <Item Title> (<severity>) [TARGET_LABEL]
  → Codex complete.
  → Gemini: RESOLVED / NEEDS MORE WORK (iteration N)
  → Archived. / Re-sending to Codex...

End-of-run summary:

agent-remediate-loop complete. [TARGET_LABEL]
Resolved: N items
  CRITICAL: N  HIGH: N  MEDIUM: N  LOW: N
Multi-iteration: <titles that needed >1 Codex pass, or "none">
Archive: .planning/archive/<TARGET_LABEL>-resolved.md

---

Constraints

• Do not skip items. Every active item must be resolved before run ends.
• Do not force a Gemini model. MCP bridge picks best available.
• Task specs to Codex: compact (location + problem + fix). No prose.
• Batch all context Codex needs into one prompt per item.
• Capture only pass/fail counts from test output. Never dump full logs.
• Do not add code comments. Do not summarize mid-run.