design: review loop — diff review can reject 'done' and commission a fresh second-pass session

Drew 2026-10-28: 'Just because it made something and says it's done, that doesn't have to be the endpoint.' Design the mechanism, living in or beside PR diff review: the reviewer may rule a change 'ready, but not good enough' and commission a NEW session — at least Specialist when the gap is depth — that reviews ALL of the work (not just the diff) and builds it better. Cover: when a fresh agent beats one with accumulated iteration memory and vice versa; how the reviewer looks WIDER than the isolated issue (adjacent code, the goal the issue serves); the verdict vocabulary (accept / accept-with-followups / second-pass / reject); and how second passes are tracked so they terminate. Apply it to this program's own PRs first.

Program: Drew's 2026-10-28 directive (full text: hatch-personal memory/topics/id-program-2026-10-28.md).
Working pattern: parallel investigations, then the named synthesis issue merges them into a full design. Route guidance: Workhorse by default; Specialist/Summit for synthesis and ramification-heavy work. A result that says "done" is not the endpoint — the orchestrator reviews it and may commission another round. Deliverables: a markdown design/investigation doc (mermaid/SVG diagrams welcome) linked from this issue, plus follow-up issues for anything buildable. Build a proof of concept where the design calls for one, but do NOT build the permanent feature on top of an unreviewed PoC.

CODE-946

Parent epic: #2055 — fleet expansion & placement program (2026-10-28 directive).

Top priority — ID program wave-1. Drew directed this be picked up in the next runs (2026-10-29): enqueued directly as triage task 3342 in repo-health-code-pilot at queue priority 20 (only breakage-class work at priority 10 outranks it). Wave-1 is the ungated investigations and designs; syntheses and PoCs stay gated on their named inputs. Investigation route: Workhorse.

🤖 Agent note · done

Agent: queue worker (repo-worker-code), Lane C
Session / ID: queue task 3342 (triage)
Found via: queue claim
Task: Triage verdict for design: review loop — diff review can reject 'done' and commission a fresh second-pass session #2025 — CONFIRMED gap, routed as a follow-up design task in the same pass
Expectation: done — verdict below; follow-up design task enqueued (packet queue-pilot/packet-2025-design.json)

Verdict: CONFIRMED — no review-loop mechanism exists today; the current diff reviewer is explicitly barred from doing what this issue asks.

Evidence (read this run, 2026-10-29):

The standing PR diff review job's charter (goal guide, current): it "reviews pull requests — commits and diffs, open and closed/merged… files issues for useful findings… Issues only — it never comments on PRs, never fixes, never merges." A reviewer that cannot comment on the PR cannot rule "ready, but not good enough" on it, and filing a fresh issue is not commissioning a session — it lands in the general backlog with no binding to the reviewed work, no pass count, and no termination rule.
The queue's terminal vocabulary has no second-pass state: a task ends complete / park / block / fail (worker instruction §6–§7), and the lifecycle protocol's label state machine (§1) has no verdict labels beyond needs-review. Nothing tracks "pass 2 of N" for any artifact, so second passes today would be untracked by construction — the exact failure the issue's tracking requirement targets.
The closest existing mechanism is one-directional: duplicate-PR salvage (protocol §8) and fleet-monitor check-ins on stalled work (§6.3) react to stuck or duplicated work, never to finished-but-mediocre work. "Done" is currently always the endpoint for the producing session.

Triage read for the design to confirm or overturn:

Verdict vocabulary maps cleanly onto existing machinery if the design wants it: accept = merge under standing criteria; accept-with-followups = merge + enqueue follow-up packets bound to the PR; second-pass = a NEW packet kind (or a triage packet with a pass-count in the payload) dispatched via the OpenChamber dispatcher at Specialist-or-above, carrying the reviewer's gap list and the whole-work scope (not just the diff); reject = block with reason class, as today.
Termination is the design's hard part, and it is a counting problem, not a judgement one: cap passes per artifact (triage suggestion: 2), record pass count + commissioning verdict in the packet payload and an agent-note:v1 on the PR, and make a second second-pass verdict on the same artifact escalate to user/review instead of commissioning pass 3.
Fresh-vs-iterating tradeoff (the issue's core question) has a fleet-local data point the design should use: this queue's own anti-evaporation history (§10) shows fresh sessions with good checkpoints routinely finish prior sessions' work correctly — evidence that fresh + well-briefed beats iterated-and-compacted for bounded work; the design should state where that flips (deep debugging state, long repro chains).

Routing: follow-up design task enqueued this pass (packet-2025-design.json: design doc at files/review-loop-design-2025.md linked from this issue, verdict vocabulary + tracking/termination design, fresh-vs-iterating analysis, application to this program's own PRs first per the issue, follow-up issues for anything buildable). This issue stays open at priority/high for that design.

agent-note:v1
state: reviewed (coverage loop-back)
Coverage pass 2026-11-03, loop-back review: this issue was re-reviewed (drift / overlap / already-handled / stale / blockers / ordering) so every open issue in the four repos is reviewed and in the system. Verdict: still live; in the system as task 7269 (triage, queued, priority 50) in repo-health-code-pilot. Labels audited and synced. If it is already handled at current main, its triage closes it with evidence; if oversized, the triage files the split; blockers belong on this issue.
Found via: coverage loop-back 2026-11-03

🤖 Agent note · picked up

Agent: queue worker (repo-worker-code), lane code-c shift
Session / ID: task 7269
Found via: queue claim
Task: Triage design: review loop — diff review can reject 'done' and commission a fresh second-pass session #2025 (review-loop design): reconcile with sibling review loop: add second_pass packet kind + review payload block to repo-task/v1 (design #2025 §5) #2310 (second_pass packet kind) — one design record should survive; verify state at current main and route.
Expectation: effort s; done = a triage verdict on design: review loop — diff review can reject 'done' and commission a fresh second-pass session #2025 naming the surviving record and the follow-up path, task 7269 completed.
Links: task 7269 in repo-health-code-pilot; sibling review loop: add second_pass packet kind + review payload block to repo-task/v1 (design #2025 §5) #2310

Triage verdict — pair reconciled: ONE design record survives; #2025's design phase is done, its decisions are Drew's (task 7269)

Verified fresh 2026-11-03 (~23:45Z):

Reconciliation of the pair (#2025 vs #2310): there are not two competing design records. The single surviving record is the design delivered for this issue by task 3382: files/review-loop-design-2025.md (keep-the-four-repos-healthy goal workspace), covering the verdict vocabulary (§3), second-pass commissioning (§§5–6), and tracking/termination (§7). #2310 is not a rival design — it is follow-up #1 of that design (implements §§5.1–5.2, 7.2), alongside #2311 (review/* labels + protocol amendment), #2312 (fleet-monitor checks), #2313 (Stage A shadow-verdict PoC), and #2314 (second-pass brief template). All five follow-ups are OPEN; none is implemented — second_pass is still absent from the repo-task/v1 schema and repo-queue.py (grep-verified this run).

What blocks the set — decisions reserved to Drew in the design (§11), still unruled:

D1 — Charter amendment: amend pr-diff-review's charter (Stage B) to permit verdict notes on in-scope PRs and second-pass enqueueing. Design recommendation: yes, Stage B scope only (epic epic: fleet expansion & placement program (2026-10-28 directive, LIST 1–5) #2055), after Stage A data. If no: queue lanes verdict each other's PRs; the standing diff reviewer stays mute on the artifacts it knows best.
D2 — Packet kind: add second_pass as a repo-task/v1 kind (§5.1) vs a permanent payload block on small_fix. Design recommendation: the kind — validation, dedupe, and health counting all get simpler. review loop: add second_pass packet kind + review payload block to repo-task/v1 (design #2025 §5) #2310 explicitly must not start until D2 is ruled — this is the immediate gate for the whole follow-up set.
D3 (pass cap 2 for the pilot; recommendation: adopt) and D4 (who verdicts non-program work at Stage C; recommendation: decide at the Stage C gate, not now) are not blocking today.

Routing: this issue stays OPEN as the decision record, labelled user/escalated + status/blocked on D1/D2. No new packet enqueued — #2310 already carries the gated implementation and is itself in the system (task 7325). Once D2 (and D1) are ruled, #2310's triage unblocks and the follow-up set proceeds in design order. Task 7269 completes as triaged.

🤖 Agent note · done

Agent: queue worker (repo-worker-code), lane code-c shift
Session / ID: task 7269
Found via: queue claim
Task: Triage design: review loop — diff review can reject 'done' and commission a fresh second-pass session #2025 — pair reconciled, surviving design record named, blockers (D1/D2) named and escalated
Expectation: done = this verdict on the issue and task 7269 completed as triaged
Links: task 7269 in repo-health-code-pilot; design files/review-loop-design-2025.md; follow-ups review loop: add second_pass packet kind + review payload block to repo-task/v1 (design #2025 §5) #2310, review loop: coin review/* label family + draft lifecycle-protocol verdict amendment (design #2025 §§3, 7.1) #2311, review loop: fleet-monitor checks for verdict/packet reconciliation (design #2025 §7.3) #2312, review loop PoC (Stage A): pr-diff-review records shadow verdicts, report distribution (design #2025 §8) #2313, review loop: second-pass session brief template from a verdict note (design #2025 §5.4) #2314

Navigation Menu

Repository navigation

design: review loop — diff review can reject 'done' and commission a fresh second-pass session #2025

13 remaining items

Triage verdict — pair reconciled: ONE design record survives; #2025's design phase is done, its decisions are Drew's (task 7269)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

design: review loop — diff review can reject 'done' and commission a fresh second-pass session #2025

Description

Activity

developing-today commented on Oct 29, 2026

dezren39 commented on Oct 29, 2026

dezren39 commented on Oct 29, 2026

dezren39 commented on Oct 29, 2026

13 remaining items

developing-today commented on Nov 3, 2026

dezren39 commented on Nov 3, 2026

dezren39 commented on Nov 3, 2026

Triage verdict — pair reconciled: ONE design record survives; #2025's design phase is done, its decisions are Drew's (task 7269)

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions