1---
2name: review-loop
3description: Drive Live Log Viewer's implement→review flows — start a review cycle for a conversation, monitor rounds, relay verdicts, and recover stuck rounds. Use when the user asks to run a review loop / review cycle on agent work, wants a fresh reviewer per round, or asks to orchestrate implement→review with the viewer.
4---
5 
6# Review loops (implement → review flows)
7 
8Live Log Viewer ships a flow engine that orchestrates the implement→review
9cycle: one long-lived implementer agent writes code, a fresh reviewer session
10audits the full diff each round, findings are relayed back automatically, and
11the cycle repeats until the reviewer approves. This skill explains how to
12drive it from an agent.
13 
14The viewer must be running (default `http://127.0.0.1:8898`). All endpoints
15are same-origin: call them from localhost without an Origin header.
16 
17## Concepts
18 
19- **Implementer** — an interactive CLI agent (claude or codex) in a tmux pane,
20  tracked by its transcript path. It lives across all rounds.
21- **Reviewer** — a fresh session per round, headless by default
22  (`codex exec` / `claude -p` with edit tools disabled), so every round is a
23  blind, independent look at the full diff.
24- **Round scope** — `git diff <baseRef>...HEAD` plus uncommitted changes.
25  `baseRef` is captured once at flow creation, so later rounds re-check
26  earlier fixes.
27- **Marker protocol** — the implementer prints a line starting with
28  `REVIEW_READY:` when the tree is reviewable; the scanner detects it and
29  starts a round. The implementer answers findings with `FIXED` or
30  `REJECTED — <reason>` per item.
31 
32## Start a flow
33 
34From the UI: open the project scheme, click the «Flow» chip above a
35conversation pane → "Start a flow" dialog (that conversation becomes the
36implementer).
37 
38From an agent:
39 
401. Spawn or pick the implementer conversation. To spawn fresh:
41   `POST /api/spawn`
42   `{"engine":"claude"|"codex","cwd":"<abs dir>","prompt":"<kickoff>","src":"<your transcript path>"}`
43   — returns the transcript `path` for claude; for codex, find the newest
44   `~/.codex/sessions/**/rollout-*.jsonl` whose `cwd` matches. **Always pass
45   `src`** with the absolute path of your own conversation transcript: the
46   viewer records the spawn as a handoff and draws the link from your
47   conversation to the implementer on the scheme; without it the new agent
48   stands as an unrelated root. Optional `effort` (claude: low…max, codex:
49   low…xhigh) and codex-only `fast: true|false` set the reasoning level and
50   speed tier per spawn.
512. Create the flow:
52 
53   ```
54   POST /api/flows
55   {
56     "implementerPath": "<transcript path>",
57     "preset": "<preset name>",            // or "roles": {implementer, reviewer}
58     "baseMode": "head" | "merge-base",
59     "mode": "auto" | "manual",
60     "reviewerMode": "headless" | "pane",
61     "roundLimit": 5
62   }
63   ```
64 
65   A role is `{engine: "claude"|"codex", model: string|null, effort: string|null}`
66   (codex effort: low|medium|high|xhigh). `GET /api/flows` lists flows and the
67   editable presets (stored in `~/.claude/viewer-state/review-loop-presets.json`).
68 
693. The engine relays its own kickoff protocol to the implementer. Instruct
70   your implementer to print `REVIEW_READY:` only when the tree is stable and
71   the build is green.
72 
73## Monitor and control
74 
75- `GET /api/flows` — states: `waiting_ready → spawning → reviewing →
76  relaying → fixing → …`, terminal `approved` / `commented` / `closed`, and
77  `needs_decision` (with `stateDetail`) when the engine will not guess.
78- `PATCH /api/flows/<id>` with `{"action": ...}`:
79  `pause`, `resume`, `set-mode`, `advance` (manual-mode transitions or force a
80  round from `waiting_ready`), `retry-round` (re-run the current round from
81  `needs_decision`), `cancel-round` (stop a running reviewer mid-round; the
82  flow lands in `needs_decision`), `extend` (+N rounds at the limit),
83  `another-round`, `close` (also stops a still-running reviewer — one click removes the reviewer side, the implementer keeps working), `set-round-limit` (absolute limit via `rounds`,
84  0 = unlimited). `advance` and `retry-round` take an optional `note` string
85  delivered to the next reviewer as the round's ready note — use it to steer
86  a re-review after cancelling.
87- Round artifacts: `~/.claude/viewer-state/flows/<flowId>/round-<n>-review.md`
88  — first line `VERDICT: APPROVE | REQUEST_CHANGES | COMMENT`, findings below.
89 
90## Recovering stuck rounds
91 
92- Restarting the viewer service (`systemctl --user restart agent-log-viewer`)
93  kills in-flight headless reviewers too — they live in the unit's cgroup.
94  Cancel the round first or let it finish; after an unavoidable restart the
95  artifact stays empty and the only path is `retry-round`.
96 
97- `needs_decision: "reviewer process is missing after server restart"` — a
98  dev-server reload killed or orphaned the headless reviewer. Check
99  `pgrep -af "codex exec"` first: if the reviewer still runs, wait for it to
100  exit, then set the flow state back to `reviewing` (edit
101  `~/.claude/viewer-state/flows.json`; the engine is stateless and re-reads
102  it) so the engine picks the verdict up from the transcript. If nothing
103  survives, `retry-round`.
104- `needs_decision: "reviewer verdict was unparseable"` — read the round
105  artifact. A usage-limit banner means the reviewer engine ran out of quota:
106  switch `roles.reviewer` in `flows.json`, then `retry-round`.
107- Round limit reached — `{"action":"extend","rounds":N}` to keep going, or
108  `close`.
109 
110## Conventions
111 
112- Prompts to agents: English.
113- One orchestrator: while the implementer fixes, do not edit the same files
114  yourself.
115- Keep flow panes/windows around after completion; the user inspects them in
116  the viewer.
117