review-loop

Review loop

A four-lens adversarial review pattern, iterated until the team converges or a budgeted number of rounds elapses. Use it when the user wants the bar set high on both correctness and polish — substantive PRs where a single review pass would miss the second-order issues four lenses catch independently.

Loop logic:

for round in 1..N:                          # N defaults to 5
  launch 4 READ-ONLY agents IN PARALLEL: correctness, adversarial, api-design, test-rigor
  wait for all 4 to report                  # they report; they never edit
  synthesize findings (convergent vs single-reviewer; rank by severity)
  if every reviewer says "CLEAN — ship it":
    stop                                    # full convergence
  if every finding this round is NIT severity (no BLOCKER/ISSUE anywhere):
    ask the user: stop here, or spend one more round?   # see Step 5
  if severity has trended down for 2 rounds straight and neither stop
     condition above has fired: ask the user ONCE — stop, or continue to budget?
  audit each finding yourself               # reviewers are wrong sometimes
  fix every accepted finding                # MAIN SESSION ONLY — see below
  commit + push
end
report final status

The single-writer rule — non-negotiable

The four reviewers are READ-ONLY. The main session is the only process that edits the worktree. Reviewers produce reports; the main session audits them, decides what to accept, and makes every change itself.

This is not a style preference. Four agents editing one worktree in parallel corrupts it, and the failure modes are quiet:

• A reviewer leaves a probe file behind (zz_probe_test.go), and the package stops compiling for everyone — including the next round's reviewers, who then report a "build failure" that is really litter.
• A reviewer break-verifies by mutating a source file and doesn't restore it. The mutation is now indistinguishable from the main session's in-flight work. In one real run a reviewer's stream-swap sat in root.go long enough that it was nearly committed; it was caught only because a test written minutes later happened to fail on it.
• A reviewer notices another reviewer's litter and helpfully runs git checkout -- <file> to clean up. That silently discarded the main session's uncommitted fix to the same file, which surfaced later as an unexplained build break.