Wire a separate review agent that emits a structured PASS/FAIL verdict, route on it to a fix agent, and cap the iterations — quality becomes mechanically self-correcting.

Guide

How to Build Review-Fix Loops

The reading path

Seven nodes, in this order — epistemic problem → artifacts → loop → gate.

1

Principle

Trust But Verify

Self-review by the producing agent is unreliable — the mental model that produced the error reads past it. An independent reviewer is the structural fix.

2

Principle

Your Work is Useless Unless Tested

Review is testing applied at the agent-output layer — untested output has unknown quality. Not optional overhead; the mechanism that converts output into verified output.

3

Primitive

Review Report

The reviewer's structured artifact. A PASS/FAIL verdict plus specific findings — the verdict field is what makes downstream routing mechanically conditional.

4

Primitive

Fix Report

The fixer's response artifact. Review Report says what is wrong; Fix Report records what was changed. Together: an auditable correction record.

5

Pattern

Review Fix Closed Loop

Connects the two artifacts into automation: PASS exits, FAIL invokes fix, output re-enters review. Includes the iteration cap that kills infinite loops on unfixable issues.

6

Pattern

Closed Loop Execution

The broader class this fits into — places Review-Fix in context and shows how it composes with other loops in a larger pipeline.

7

Primitive

Phase Gate

Review is a gate between phases. A gate holds the pipeline until a condition is satisfied — the review verdict is the gate condition.

Read in order. Skip Trust But Verify and the rest collapses — the loop's reason to exist is the principle it operationalizes.

The two artifacts

Review Report specifies what's wrong. Fix Report records what changed.

review-report.yaml

reviewer

verdict: FAIL

findings:

- id: F-01

severity: blocker

file: src/auth.py:42

issue: "token never invalidated on logout"

- id: F-02

severity: minor

issue: "missing null check"

The verdict field is load-bearing. It's what the router reads — no interpretation required, no natural-language parsing, no branch on "the reviewer seemed concerned."

fix-report.yaml

fixer

addresses: [F-01, F-02]

changes:

- finding: F-01

file: src/auth.py

action: "add revoke() on /logout"

- finding: F-02

action: "guard with if token is None"

status: ready_for_rereview

Each fix is traceable to a finding. Re-review knows exactly what to re-check — and unresolved findings are flagged when the fixer skipped them.

Two structured files. No prose summaries passed between agents — if the next agent has to interpret English, the loop isn't mechanical.

The loop

Verdict routes. Cap prevents thrash. Pass exits the gate.

producer → reviewer → verdict → (exit | fix → re-enter)

step 1

Producer

emits output

→

step 2

Reviewer

writes Review Report

→

step 3

Verdict?

PASS or FAIL

PASS→ exit gate

Phase Gate opens. Output is promoted to the next phase. The loop terminates cleanly — no further agents invoked. → downstream consumes verified output

FAIL↻ fix & re-review

Fix agent invoked. Consumes findings, edits files, writes Fix Report. Output re-enters the reviewer. Iteration counter ticks. ↻ loop back to step 2

Without routing on a structured verdict, the loop becomes advisory — humans stay in the middle, reading review prose and deciding what to do next.

iteration cap: typical 3 — beyond that, escalate

The cap is non-negotiable. Unfixable issues loop forever without one — budget burns, nothing ships.

What this guide teaches

Seven nodes across three layers — principles, primitives, patterns.

Principle

Trust But Verify

An author can't catch their own blind spots — an independent reviewer can.

Principle

Your Work is Useless Unless Tested

Untested output has unknown quality. Review converts output into verified output.

Primitive

Review Report

Structured PASS/FAIL verdict plus findings — the branch condition.

Primitive

Fix Report

Changes-per-finding record — the auditable correction counterpart.

Pattern

Review Fix Closed Loop

The routing logic: PASS exits, FAIL fixes and re-enters, cap prevents thrash.

Pattern

Closed Loop Execution

The broader category — how Review-Fix composes with other loop types.

Primitive

Phase Gate

The verdict is the gate condition — pipeline holds until PASS.

Shape

principle → artifact → loop → gate

The sequence. Skip any layer and the loop leaks — prose instead of verdicts, or verdicts nobody enforces.

Each node is independently useful — only the sequence makes the loop mechanical.

Where to go next

Two adjacent guides compose with this one.

how-to-use-hooks

If you want enforcement. Hooks can require the review loop to run before a phase completes — the two mechanisms compose into a non-bypassable gate.

how-to-build-metaagents

If you want orchestration. The review and fix agents are discrete — this guide covers the layer that spawns and sequences them across a full pipeline.

Hooks make the gate binding. Meta-agents wire the gate into a larger flow. This guide sits in the middle.

The discipline

A review agent without a structured verdict is advisory. A loop without an iteration cap is a leak.

Independent reviewer, PASS/FAIL field, conditional route, fix agent, re-enter, cap. Six parts — remove any one and a human quietly slips back into the middle. The architecture is what makes quality self-correcting; the prose can't.