/record-review — review what you just built, write down what you decided

This is the other end of /human-review. That skill writes up a review that already happened; this one is what happens. It runs after the implementation, in the same conversation that did it — however that implementation went: a ticket, a pairing session, a fix that grew. It exists because the most valuable thing a coding agent knows about its own change is the part that never reaches the diff:

• which review findings it accepted, and which it read and declined — and why;
• which reading of an ambiguous ticket it chose, which reading it did not take, and how sure it is that it chose right.

That last number — confidence:, in [0, 1] — is the cheapest thing on the page and the one nothing else can supply: a reviewer with an hour and eleven assumptions needs to know which three were close calls, and only the agent that made them knows. It is honest or it is noise, which is why prompt.md says so in as many words: 0.9 on everything is a lie the page will show. The scale is fixed so the numbers mean the same thing across runs — 1.0 the ticket left no other reading, 0.5 a coin flip, below 0.3 expecting to be corrected — and it is refused outside that range rather than clamped.

All of it lives in a conversation and dies with it. review-points.md is where it is written down instead, at the repository root, committed with the fixes — so a reviewer sees the artifact arrive in the PR's own file list rather than taking a generated page's word for it. The page then renders it; it does not invent it.

Same conversation, or nobody's decisions. Run from a fresh conversation, the findings would still come back, but the accept/decline and the assumptions would be an outsider's guesses about choices it never made — and they read on the page exactly like the real ones. If the conversation that wrote the code is gone, resume it (claude --resume <id>, or reopen the chat in VS Code) rather than start a new one.

Headless runs

claude -p / copilot -p end when the model ends its turn: nothing backgrounded ever reports back. The whole flow — prepare, reviewers, ci, finish — runs in one turn, every command in the foreground. A run that stops "waiting for X" has not recorded its review.

Run it

Read prompt.md beside this file and follow it, with $ARGUMENTS as the base of the change set (empty: the merge-base with origin/main).

record-review.py does the mechanical half, so the agent's turns go to judgement. The first run in VS Code spent 332 tool calls, most of them on things with one right answer: where the format file lives, what the base is, the diff a hunk at a time, four reviewer prompts, the trailers, seventeen hand-written PR comments. prepare resolves the change set, writes the diff to one file and one brief per reviewer lens, and runs the repository's own pre-push checks as a dry-run — the cheapest reviewer there is, and the one four model reviewers missed when the Spectral hook later refused the push. finish fills the front-matter, carries every file:line across the fixes to the tree it commits (and refuses to commit while one points at a line that is gone or blank — anchors: review-commit then tells the page there is nothing left to remap), checks the file, commits with the trailers — amending its own commit when re-run before it was pushed, so a round is one [auto-fix] commit — and derives the PR comments (push-pr-comments.py --from-review-points). What is left to the agent: run the reviewers, decide each finding, write the piles.

From a shell:

for c in "${CLAUDE_PLUGIN_ROOT:-/nonexistent}/skills/record-review" \
         "${HUMAN_REVIEW_HOME:-/nonexistent}/../record-review" \
         "$(readlink -f .claude/skills/record-review 2>/dev/null)" \
         "$(readlink -f ~/.copilot/skills/record-review 2>/dev/null)" \
         "$HOME/workspace/human-review/skills/record-review"; do
  [ -f "$c/prompt.md" ] && { PROMPT="$c/prompt.md"; break; }
done

It works in any harness that loads skills and can start subagents. Claude Code runs its built-in /code-review high as the review pass; VS Code Copilot Chat (which reads .claude/skills/, .github/skills/ and ~/.copilot/skills/) and the Copilot CLI start four read-only reviewer subagents instead, one lens each. For VS Code, no plugin is needed — link both skills into the personal skills folder and open a new chat:

ln -s ~/workspace/human-review/skills/record-review ~/.copilot/skills/record-review
ln -s ~/workspace/human-review/skills/human-review  ~/.copilot/skills/human-review

Headless Copilot CLI (copilot -p) cannot invoke this skill by name. It is disable-model-invocation: true, and in -p mode there is no user to type the slash command, so /record-review as the prompt answers Skill not found. Hand it the files instead — Read <skill dir>/SKILL.md and <skill dir>/prompt.md, then follow them — with the skill dir found as above. And pass --harness copilot-cli to prepare and finish: a copilot -p started from a Claude Code session inherits CLAUDE_CODE_SESSION_ID, and without the flag the review is recorded as that Claude session's.

Either way the reviewers only find; the conversation that wrote the code decides.

What the flow downstream depends on

Three things, and a fourth for the pull request. Each is read by a script, so getting one wrong is a silent loss of exactly one row on the page:

The trailers are written by record-review.py finish, and the harness may write after them — or ask finish to: --commit-trailer "Co-authored-by: Copilot <…>" (repeatable) appends a line of its own, so no harness has to patch the script to sign the commit. Claude Code appends Co-Authored-By: Claude … as a paragraph of its own, which puts the three keys in the penultimate paragraph — and git's %(trailers:key=…) only parses the last one, so it returns empty for all three. The first real run of this flow produced two correctly trailered commits that the page reported as "not recorded" for exactly that reason. review-commits.py therefore reads the keys off any line of %B, with %(trailers) as the first pass only. Nothing is asked of the agent beyond one key per line: a paragraph landing after them is expected and harmless.

The pull request names the model and effort that wrote it. This skill never opens the PR, but whoever does ends its description with the line `authoring-sessions.py --base

🤖 Generated with [Claude Code](https://claude.com/claude-code) · Opus 5.5 (effort: high, context: 1M)

The words are the commit trailer's, Co-Authored-By: Claude Opus 5.5 (effort: high, context: 1M), and they are read, not remembered: every assistant record of a Claude transcript carries model and effort, and a turn past 200k tokens proves the 1M window. Where the transcript is gone, the implementation commit's own Co-Authored-By: names the model (and the effort, when it spells it out): the commit Implements: names, else the oldest one past a revert to the base — so the line always says which model, and its version. PR #49 said only "Generated with Claude Code", and its title said "by Opus" — which Opus, at what effort, was in nobody's words until the transcript was opened. review-cost.json now records the same (efforts, peakContext on each Claude entry), and the page shows it under the $ tab's prices and on the review chip's hover (Coded by …). With neither a transcript nor a trailer naming a model, it prints the bare line and exits 5.

Two commits at least: the implementation, then the review. The implementation may already be several commits by the time this runs — they are left as they are, and Implements: names the last of them. The review is one commit: the accepted fixes plus review-points.md, its subject starting with [auto-fix] — as does any later commit applying a reviewer's finding — so git log --grep='\[auto-fix\]' finds everything the agent changed on the review's say-so, and review-commits.py lists those commits (and falls back to the last one when a squash lost the trailers). That split is what makes "what did reviewing cost, against writing it" a measurement instead of an estimate — the commits are the only timestamps in the whole flow that a rebase cannot move without also moving the work.

Which review pass

In Claude Code, the harness built-in /code-review (effort levels low…ultra, --fix, --comment) — not the code-review:code-review plugin, which needs a real GitHub PR and ends by posting a gh pr comment.

--fix is refused deliberately, and so is a reviewer subagent with write access. Either applies the findings to the working tree, which destroys the accept/decline information this whole flow is built to capture: afterwards there is a diff, and no record of which of its lines the agent would have argued with.

Never re-run a pass to "confirm" a finding. Two runs over the same diff word and rank their findings differently, so a second invocation does not confirm the first — it produces a different review at full price, and whichever ran last wins.

The demo PR is this flow plus hand retouches

petclinic's test-pr branch ran this flow, then has a handful of deliberate retouches on top — one per review-page tab, so the demo has something to show everywhere. demo/DEMO-PR-RECIPE.md lists them, with the commit each one landed in and how to redo it.