Writer/reviewer split
One agent writes the code. A different model, in a fresh context, reviews the exact commit it produced. You (the controller) own the brief, the acceptance criteria, your own checks, and the merge. Nothing ships on the writer's say-so, and nothing ships on a verdict that isn't the last line of the reviewer's final message.
When to use it
- Any change you'd want a second pair of eyes on: features, bug fixes, refactors, anything touching security, money, state, or releases.
- Work you're delegating to a headless coding agent (Claude Code, Codex CLI, or similar) that runs without you watching.
- Skip it for a one-line typo fix you can verify by reading the diff.
Roles
- Controller: you, or the main session. Writes the brief, decides acceptance, runs the checks, merges. It doesn't write production code itself. When it finds a defect, it describes the evidence and delegates the fix.
- Writer: a coding agent working in its own worktree. It commits its work.
- Reviewer: a different model from the writer, in a fresh session, with read-only access to the exact commit. Two runs of the same model tend to share blind spots.
Procedure
- Get the real baseline. Look at the repo itself: branch, dirty state, how tests run, what's deployed. Run
git worktree list and git rev-list --count main..<branch> for existing branches. An earlier fix for the same symptom is often sitting unmerged on a stale branch; if so, tell the writer to cherry-pick it instead of re-deriving it. Check whether another agent is already writing in this repo, and keep your lane's files away from theirs.
- Isolate. Create a worktree per task:
git worktree add ../wt-<task> -b <task> main. Run one writer per worktree. Keep briefs, logs and result files outside the tree, because anything inside it is one git add -A away from being committed.
- Write the brief from references/brief-template.md: the user-visible outcome and non-goals, the files to read first, constraints, the tests required, prohibited actions, and "make one commit". Add "Don't ask questions; decide within these constraints" and grant scoped follow-on edits ("you may update direct callers of a function whose signature you change"). Headless agents otherwise stop to ask a question and exit 0 with nothing committed. If the fix is already diagnosed down to the line, write the exact edit as numbered steps and tell the agent not to investigate further.
- Launch the writer with a working directory, a turn cap and a spend cap. Long runs need the launch pattern below. Put turn-budget guidance in the brief ("manage turns, run the full tests once near the end, leave turns to commit") so the run doesn't end with partial source.
- Classify the result from the tree, not the exit code. Run
git status, git log, git diff --stat and git diff --check, then run the tests yourself. See Partial runs below.
- Read the writer's closing notes as findings. Agents often bury real defects under "things to know" or "you might want to revisit". Mark each one as a blocker or as accept-with-note, and pass the accepted ones to the reviewer as already known so it spends its budget elsewhere.
- Brief the reviewer from references/review-template.md. Give it the exact commit SHA, the diff range, read-only rules, the probe list for this kind of change, and the required last line:
VERDICT: PASS or VERDICT: FAIL, plain text, outside any code block. Keep the scope narrow. A scoped diff plus a probe list beats "audit the repo".
- Extract the verdict with scripts/extract_verdict.sh. Never extract a verdict from a raw transcript; use the CLI's structured or final-message output. For Codex CLI, have it write the final message to its own file (
codex exec -o review-final.md ...) and run extract_verdict.sh review-final.md. For Claude Code, save claude -p --output-format json output and run extract_verdict.sh --format claude-json review.json, which reads the result of the last "type":"result" line. The script ignores fenced code blocks, and the verdict counts only if the last non-blank line outside them is exactly VERDICT: PASS or VERDICT: FAIL. Exit 0 means PASS, 1 means FAIL, and 2 means there's no verdict (a missing or empty file, no verdict on the last line, or a usage-limit or capacity error). Treat exit 2 as no review, never as a weak pass.
- Read the findings, not just the verdict. If a PASS lists a security or data-integrity finding that says it must be fixed before release, treat it as a FAIL. Severity labels never override a finding's evidence.
- On FAIL, quarantine the commit. Nothing merges. Turn each finding into a focused failing test, and send a narrow correction brief to a fresh writer pass. Keep the reviewer's exact reproduction and acceptance boundary; don't fold several findings into "harden it".
- Re-review the new SHA, and prove the regressions. Correction passes usually write the fix and its test together, so a new test can pass on the old code and prove nothing. Make the re-review run each new test against the old commit in a throwaway worktree (
git worktree add --detach /tmp/old <old-sha>), confirm it fails there and passes on the new commit, then remove the throwaway tree. Report any test that's green on both.
- Check the trajectory with the complexity stop rule below before you send another correction brief.
- Merge the reviewed SHA exactly. Fast-forward to it, confirm
HEAD equals the reviewed SHA, rerun the suite on the merged tree, and remove the worktree. Report authorship honestly: which model wrote it, which reviewed it, and what you ran yourself.
Rules, and why
- Use a different model to review. A second run of the writer's model tends to repeat the writer's assumptions.
- Review the exact commit, not the working tree. Uncommitted bytes and a later rebase are different artifacts from what was reviewed.
- Keep the reviewer read-only and check that it stayed that way. Record
HEAD and git status before and after the review; a reviewer that edits is now a writer.
- Accept a verdict only as the last line of the final message. Reviewers echo their brief and print templates and fixtures, so a grep for
VERDICT anywhere, even anchored, can find a line that isn't the reviewer's conclusion. Take the final message, skip code blocks, and read only its last line.
- Check for usage-limit and capacity errors before reading any verdict. Some CLIs print these and still exit 0, so a run that never reviewed anything looks clean.
- Treat execution and verdict as separate evidence. An auth error, a tool denial, truncated output or a turn cap means there was no review. Retry through another independent read-only path.
- Never extract a verdict from a raw transcript; use the CLI's structured or final-message output. Transcripts repeat tool output, echoed briefs and quoted logs, and every attempt to scrape the final message out of one can be fooled by a log the reviewer quotes.
- Spot-check the reviewer's key claims. One grep or one test run confirms or kills a claim cheaply, and catches wrong premises you put in the brief.
- Keep a static-only review labelled as one. If the reviewer couldn't run commands, its verdict covers reading only. Your own test runs supply the rest, and the report should say both.
- Never ship a promise the code doesn't keep. A displayed counter nothing increments or a button with no action passes tests that only check rendering. Remove the rendering, keep the data field, and check your own copy for the same claim.
- Keep the brief in a file. Inline prompts with backticks inside shell double quotes get mangled by command substitution before the agent ever sees them.
Long-run launch pattern
A pass that takes more than a few minutes should outlive the session that started it:
# Detach from your session; close stdin so the agent can't block waiting on it.
nohup bash -c 'cd ../wt-task && <agent-cli> <headless-flags> \
"Read /path/outside/tree/brief.md and do exactly what it says. Do not ask questions." \
< /dev/null > /path/outside/tree/writer.log 2>&1' >/dev/null 2>&1 &
echo $! > /path/outside/tree/writer.pid
Use a transient service unit, tmux or nohup, whichever your host supports. Then watch the PID or unit in a separate waiter loop (while kill -0 "$PID" 2>/dev/null; do sleep 30; done). Keep these rules:
- Don't put a hard timeout on a long build. Hitting it kills the agent with no result and leaves half-done work uncommitted.
- If your tool wrapper notifies when its shell exits, a trailing
& makes it report "done" while the agent is still running.
- Reviews hit capacity blips too. Run them in a bounded retry loop that stops as soon as a verdict appears:
for i in 1 2 3 4; do
rm -f review-final.md # never let an earlier attempt's answer count
codex exec <headless-flags> -o review-final.md \
"Read review-brief.md and do exactly what it says." < /dev/null > review.log 2>&1
scripts/extract_verdict.sh review-final.md >/dev/null; rc=$?
[ "$rc" -ne 2 ] && break
cp review.log "review-attempt$i.log"; sleep 600
done
A usage-limit or capacity error lands in review.log, not in the final message, so the final file is missing or empty and the script exits 2. Read review.log for the reason; never for the verdict.
- A usage-limit message with no work done is no run, not a failed pass. Relaunch the same brief after the reset. Don't re-brief it, and don't count it against the stop rule.
Partial runs
An agent can exit on a turn cap, a timeout or a usage limit after writing a lot of correct code, or after finishing only the failing-test half of the job. It can also exit 0 with an empty result file. Classify the tree, not the exit code:
- Inspect
git status and the diff before you reset anything or launch another writer.
- Run the focused tests, the full suite, and the build or syntax checks on the tree as it is.
- Put it in one class: clean completion, coherent dirty tree that's green, intentional red (tests written, fix pending), or unexplained mixed state.
- If it's coherent, resume the same session with only the missing items, and tell it what's already in the tree. If it stopped at red, check the failure is the expected one and ask only for the fix. Leave the test alone.
- If it's mixed or the authorship is unclear, move it to a recovery worktree instead of guessing.
- After any resumed pass exits, look at git again before you resume a second time. It may have committed cleanly and only failed while writing its report.
- Before committing leftovers yourself, check the staged file set so a bookkeeping-only commit can't leave the real fix dirty.
Complexity stop rule
Review is supposed to converge. Read the trajectory, not the cycle count.
- Narrowing: each round has fewer findings, confined to one area, and the earlier serious ones stay closed. That's convergence. Keep going with directive briefs that carry the reviewer's exact line-level fixes.
- Churn: three rounds that each expose a different class of defect, or a shared-state or provenance defect every round. Stop patching and reassess:
- Restate the user's actual deliverable, separately from the tooling you built to get there.
- Ask whether a smaller design removes the problem: a narrower input, a simple state machine, a supervised manual step.
- Keep the last good baseline on its branch and redesign on a fresh one.
- Make invariants structural (transactions, unique ids, idempotent writes, kernel locks, real parsers) instead of layering checks on mutable state. Open-ended heuristics such as free-text classifiers, regex redactors and regex HTML editing churn forever because their input space is unbounded. Narrow the input or delete the route instead.
- Keep real work on the deliverable moving while you redesign.
- The same race every round in one mechanism (verify-then-act): stop asking for fixes. Write the exact ordered sequence into a directive brief, name the one residual you accept, and tell the reviewer not to raise it again.
Report two lines when this happens: deliverable state and tooling state. A passing test suite for the tooling isn't progress on the deliverable.
Files
- references/brief-template.md: fill-in coding brief.
- references/review-template.md: fill-in reviewer brief with probe lists and the exact last line.
- references/pitfalls.md: failure modes we've hit, as rules.
- scripts/extract_verdict.sh: print the verdict from the last line of the reviewer's final-message file (
plain) or Claude Code JSON result (claude-json), or exit 2. Needs bash and python3.
- tests/test_extract_verdict.py: run with
python3 -m unittest discover -s skills/writer-reviewer-split/tests from the repo root.
1---2name: writer-reviewer-split3description: "Use when you hand coding work to an AI agent and want it checked before it ships. One model writes the change in an isolated worktree, a different model reviews the exact commit read-only, and nothing merges unless the reviewer's final line is VERDICT: PASS."4metadata:5 source: https://skillmd.com/skills/satisfying-systems/writer-reviewer-split6---78# Writer/reviewer split910One agent writes the code. A different model, in a fresh context, reviews the exact commit it produced. You (the controller) own the brief, the acceptance criteria, your own checks, and the merge. Nothing ships on the writer's say-so, and nothing ships on a verdict that isn't the last line of the reviewer's final message.1112## When to use it1314- Any change you'd want a second pair of eyes on: features, bug fixes, refactors, anything touching security, money, state, or releases.15- Work you're delegating to a headless coding agent (Claude Code, Codex CLI, or similar) that runs without you watching.16- Skip it for a one-line typo fix you can verify by reading the diff.1718## Roles1920- **Controller**: you, or the main session. Writes the brief, decides acceptance, runs the checks, merges. It doesn't write production code itself. When it finds a defect, it describes the evidence and delegates the fix.21- **Writer**: a coding agent working in its own worktree. It commits its work.22- **Reviewer**: a *different* model from the writer, in a fresh session, with read-only access to the exact commit. Two runs of the same model tend to share blind spots.2324## Procedure25261. **Get the real baseline.** Look at the repo itself: branch, dirty state, how tests run, what's deployed. Run `git worktree list` and `git rev-list --count main..<branch>` for existing branches. An earlier fix for the same symptom is often sitting unmerged on a stale branch; if so, tell the writer to cherry-pick it instead of re-deriving it. Check whether another agent is already writing in this repo, and keep your lane's files away from theirs.272. **Isolate.** Create a worktree per task: `git worktree add ../wt-<task> -b <task> main`. Run one writer per worktree. Keep briefs, logs and result files *outside* the tree, because anything inside it is one `git add -A` away from being committed.283. **Write the brief** from [references/brief-template.md](references/brief-template.md): the user-visible outcome and non-goals, the files to read first, constraints, the tests required, prohibited actions, and "make one commit". Add "Don't ask questions; decide within these constraints" and grant scoped follow-on edits ("you may update direct callers of a function whose signature you change"). Headless agents otherwise stop to ask a question and exit 0 with nothing committed. If the fix is already diagnosed down to the line, write the exact edit as numbered steps and tell the agent not to investigate further.294. **Launch the writer** with a working directory, a turn cap and a spend cap. Long runs need the launch pattern below. Put turn-budget guidance in the brief ("manage turns, run the full tests once near the end, leave turns to commit") so the run doesn't end with partial source.305. **Classify the result from the tree, not the exit code.** Run `git status`, `git log`, `git diff --stat` and `git diff --check`, then run the tests yourself. See *Partial runs* below.316. **Read the writer's closing notes as findings.** Agents often bury real defects under "things to know" or "you might want to revisit". Mark each one as a blocker or as accept-with-note, and pass the accepted ones to the reviewer as already known so it spends its budget elsewhere.327. **Brief the reviewer** from [references/review-template.md](references/review-template.md). Give it the exact commit SHA, the diff range, read-only rules, the probe list for this kind of change, and the required last line: `VERDICT: PASS` or `VERDICT: FAIL`, plain text, outside any code block. Keep the scope narrow. A scoped diff plus a probe list beats "audit the repo".338. **Extract the verdict** with [scripts/extract_verdict.sh](scripts/extract_verdict.sh). Never extract a verdict from a raw transcript; use the CLI's structured or final-message output. For Codex CLI, have it write the final message to its own file (`codex exec -o review-final.md ...`) and run `extract_verdict.sh review-final.md`. For Claude Code, save `claude -p --output-format json` output and run `extract_verdict.sh --format claude-json review.json`, which reads the `result` of the last `"type":"result"` line. The script ignores fenced code blocks, and the verdict counts only if the last non-blank line outside them is exactly `VERDICT: PASS` or `VERDICT: FAIL`. Exit 0 means PASS, 1 means FAIL, and 2 means there's no verdict (a missing or empty file, no verdict on the last line, or a usage-limit or capacity error). Treat exit 2 as *no review*, never as a weak pass.349. **Read the findings, not just the verdict.** If a PASS lists a security or data-integrity finding that says it must be fixed before release, treat it as a FAIL. Severity labels never override a finding's evidence.3510. **On FAIL, quarantine the commit.** Nothing merges. Turn each finding into a focused failing test, and send a narrow correction brief to a fresh writer pass. Keep the reviewer's exact reproduction and acceptance boundary; don't fold several findings into "harden it".3611. **Re-review the new SHA, and prove the regressions.** Correction passes usually write the fix and its test together, so a new test can pass on the old code and prove nothing. Make the re-review run each new test against the old commit in a throwaway worktree (`git worktree add --detach /tmp/old <old-sha>`), confirm it fails there and passes on the new commit, then remove the throwaway tree. Report any test that's green on both.3712. **Check the trajectory** with the complexity stop rule below before you send another correction brief.3813. **Merge the reviewed SHA exactly.** Fast-forward to it, confirm `HEAD` equals the reviewed SHA, rerun the suite on the merged tree, and remove the worktree. Report authorship honestly: which model wrote it, which reviewed it, and what you ran yourself.3940## Rules, and why4142- **Use a different model to review.** A second run of the writer's model tends to repeat the writer's assumptions.43- **Review the exact commit, not the working tree.** Uncommitted bytes and a later rebase are different artifacts from what was reviewed.44- **Keep the reviewer read-only and check that it stayed that way.** Record `HEAD` and `git status` before and after the review; a reviewer that edits is now a writer.45- **Accept a verdict only as the last line of the final message.** Reviewers echo their brief and print templates and fixtures, so a grep for `VERDICT` anywhere, even anchored, can find a line that isn't the reviewer's conclusion. Take the final message, skip code blocks, and read only its last line.46- **Check for usage-limit and capacity errors before reading any verdict.** Some CLIs print these and still exit 0, so a run that never reviewed anything looks clean.47- **Treat execution and verdict as separate evidence.** An auth error, a tool denial, truncated output or a turn cap means there was no review. Retry through another independent read-only path.48- **Never extract a verdict from a raw transcript; use the CLI's structured or final-message output.** Transcripts repeat tool output, echoed briefs and quoted logs, and every attempt to scrape the final message out of one can be fooled by a log the reviewer quotes.49- **Spot-check the reviewer's key claims.** One grep or one test run confirms or kills a claim cheaply, and catches wrong premises you put in the brief.50- **Keep a static-only review labelled as one.** If the reviewer couldn't run commands, its verdict covers reading only. Your own test runs supply the rest, and the report should say both.51- **Never ship a promise the code doesn't keep.** A displayed counter nothing increments or a button with no action passes tests that only check rendering. Remove the rendering, keep the data field, and check your own copy for the same claim.52- **Keep the brief in a file.** Inline prompts with backticks inside shell double quotes get mangled by command substitution before the agent ever sees them.5354## Long-run launch pattern5556A pass that takes more than a few minutes should outlive the session that started it:5758```bash59# Detach from your session; close stdin so the agent can't block waiting on it.60nohup bash -c 'cd ../wt-task && <agent-cli> <headless-flags> \61 "Read /path/outside/tree/brief.md and do exactly what it says. Do not ask questions." \62 < /dev/null > /path/outside/tree/writer.log 2>&1' >/dev/null 2>&1 &63echo $! > /path/outside/tree/writer.pid64```6566Use a transient service unit, `tmux` or `nohup`, whichever your host supports. Then watch the PID or unit in a separate waiter loop (`while kill -0 "$PID" 2>/dev/null; do sleep 30; done`). Keep these rules:6768- Don't put a hard timeout on a long build. Hitting it kills the agent with no result and leaves half-done work uncommitted.69- If your tool wrapper notifies when its shell exits, a trailing `&` makes it report "done" while the agent is still running.70- Reviews hit capacity blips too. Run them in a bounded retry loop that stops as soon as a verdict appears:7172```bash73for i in 1 2 3 4; do74 rm -f review-final.md # never let an earlier attempt's answer count75 codex exec <headless-flags> -o review-final.md \76 "Read review-brief.md and do exactly what it says." < /dev/null > review.log 2>&177 scripts/extract_verdict.sh review-final.md >/dev/null; rc=$?78 [ "$rc" -ne 2 ] && break79 cp review.log "review-attempt$i.log"; sleep 60080done81```8283 A usage-limit or capacity error lands in `review.log`, not in the final message, so the final file is missing or empty and the script exits 2. Read `review.log` for the reason; never for the verdict.8485- A usage-limit message with no work done is *no run*, not a failed pass. Relaunch the same brief after the reset. Don't re-brief it, and don't count it against the stop rule.8687## Partial runs8889An agent can exit on a turn cap, a timeout or a usage limit after writing a lot of correct code, or after finishing only the failing-test half of the job. It can also exit 0 with an empty result file. Classify the tree, not the exit code:90911. Inspect `git status` and the diff before you reset anything or launch another writer.922. Run the focused tests, the full suite, and the build or syntax checks on the tree as it is.933. Put it in one class: clean completion, coherent dirty tree that's green, intentional red (tests written, fix pending), or unexplained mixed state.944. If it's coherent, resume the same session with only the missing items, and tell it what's already in the tree. If it stopped at red, check the failure is the expected one and ask only for the fix. Leave the test alone.955. If it's mixed or the authorship is unclear, move it to a recovery worktree instead of guessing.966. After any resumed pass exits, look at git again before you resume a second time. It may have committed cleanly and only failed while writing its report.977. Before committing leftovers yourself, check the staged file set so a bookkeeping-only commit can't leave the real fix dirty.9899## Complexity stop rule100101Review is supposed to converge. Read the trajectory, not the cycle count.102103- **Narrowing**: each round has fewer findings, confined to one area, and the earlier serious ones stay closed. That's convergence. Keep going with directive briefs that carry the reviewer's exact line-level fixes.104- **Churn**: three rounds that each expose a *different class* of defect, or a shared-state or provenance defect every round. Stop patching and reassess:105 1. Restate the user's actual deliverable, separately from the tooling you built to get there.106 2. Ask whether a smaller design removes the problem: a narrower input, a simple state machine, a supervised manual step.107 3. Keep the last good baseline on its branch and redesign on a fresh one.108 4. Make invariants structural (transactions, unique ids, idempotent writes, kernel locks, real parsers) instead of layering checks on mutable state. Open-ended heuristics such as free-text classifiers, regex redactors and regex HTML editing churn forever because their input space is unbounded. Narrow the input or delete the route instead.109 5. Keep real work on the deliverable moving while you redesign.110- **The same race every round** in one mechanism (verify-then-act): stop asking for fixes. Write the exact ordered sequence into a directive brief, name the one residual you accept, and tell the reviewer not to raise it again.111112Report two lines when this happens: deliverable state and tooling state. A passing test suite for the tooling isn't progress on the deliverable.113114## Files115116- [references/brief-template.md](references/brief-template.md): fill-in coding brief.117- [references/review-template.md](references/review-template.md): fill-in reviewer brief with probe lists and the exact last line.118- [references/pitfalls.md](references/pitfalls.md): failure modes we've hit, as rules.119- [scripts/extract_verdict.sh](scripts/extract_verdict.sh): print the verdict from the last line of the reviewer's final-message file (`plain`) or Claude Code JSON result (`claude-json`), or exit 2. Needs bash and python3.120- [tests/test_extract_verdict.py](tests/test_extract_verdict.py): run with `python3 -m unittest discover -s skills/writer-reviewer-split/tests` from the repo root.