Ultra review

/coograph-review is one reviewer over the working tree: the right size for most changes. /coograph-ultra-review is for the change that is big or dangerous enough that one reader misses things. Several hostile reviewers, one question each; every finding attacked by independent refuters before it reaches the report; a verdict; a stop rule.

It is optional on purpose. A run costs about a million tokens and twenty minutes. The agent points it out when a change qualifies and never runs it unasked.

Claude Code only: it runs as a saved workflow through the Workflow tool. In other tools the skill describes the same procedure to do by hand — one @Reviewer per dimension, then a pass that tries to refute each finding.

When to run it

More than about fifteen files, or a stack of commits going to people for approval.
Queue jobs, cache claims, locks, retries, redelivery, timeouts, status transitions.
Anything that deletes, moves, overwrites or migrates data.
A contract between two services, or a client and a server.
A plan for such a change, before the code exists — plan mode is the cheapest place to find a design hole.

Not for a small, local change. The everyday review is enough there.

On the stack it was built on — 21 pull requests, about 176 commits — it found, after ordinary reviews had approved: a lock released twice, a test that passed without its fix, and a queued job that could overwrite a customer’s files. The story is in the blog post.

What a run does

Stage	What happens
Scope	one scout (Haiku) resolves the PR or commits to their files and the new-side line ranges they changed, and asks the code graph for callers and importers of what changed
Review	one reviewer per dimension reads the code at the reviewed commit and returns findings, each with a verbatim quote, file:line and a concrete failure scenario — inputs and state on one side, the wrong outcome on the other. No quote, no finding.
Verify	every Critical and Warning goes to refuters with distinct lenses: does the quoted line exist and do what the claim says; does the scenario actually occur, or does a guard stop it; does an existing test contradict the reading. A finding survives only if none refutes it.
Report	one Markdown report with Critical / Warning / Nit per commit, the follow-ups, what was verified OK, the missing tests, the refuted findings with their reasons, and a verdict. The footer carries mode, agent count and tokens.

The default dimensions are generic: state, lifecycle and concurrency; data-loss and destructive paths; contracts and compatibility; tests that pass regardless. A project passes its own with dimensions.

Findings in the lines the commits changed are blocking. Findings in adjacent, pre-existing code are follow-ups: reported, recorded, never a reason to block and never looped on. The verdict is REQUEST_CHANGES only for blocking findings.

Modes

Mode	When	Reviewers	Lenses	Cost (measured)
`full`	the first review of a PR or commit batch, and the one review of the whole PR once every fix is in (`pr: N`)	4 on the session model, blast radius from the code graph	2 (Opus, high effort)	1.2–1.6M tokens, 17–22 min; a 33-commit PR: 3.1M, 39 min
`delta`	a fix batch after a `full` run: are the previous findings fixed, and what did the changed lines break	2 on Sonnet, no blast radius	1	about 0.5M, about 17 min
`plan`	before writing code that touches lifecycle or concurrency	2 on the session model, over the plan text and the code it names and its callers	1	1.0–1.4M, about 20 min — a full run’s price; it pays because it runs before the code exists

mode is inferred: plan given → plan, previous given → delta, else full.

Running it

The skill scopes the input in the conversation, proposes a model plan for the run — reading the project’s models block in openspec/config.yaml when it has one, else the mode’s defaults — and asks before anything runs. Then:

Workflow scriptPath: "<absolute path to the project>/.github/skills/coograph-ultra-review/workflow.js"
args: {"repo": "<absolute path to the project>", "pr": 364}
args: {"repo": "...", "commits": ["c78bdd7", "f04a228"]}
args: {"repo": "...", "commits": ["3d6046a8"], "previous": [{"severity": "critical", "file": "app/Jobs/X.php", "line": 105, "claim": "...", "fix": "..."}]}
args: {"repo": "...", "plan": "<the plan text>", "files": ["app/Jobs/X.php"]}

Argument	Meaning
`repo`	the repository’s absolute path — required
`pr` / `commits`	what to review: a pull request number, or commit hashes (newest last). A stacked PR: its own commits, not the base’s
`previous`	delta mode: the last run’s `findings` (file, line, claim, fix, severity)
`plan`, `files`	plan mode: the plan text (or a path the reviewers can read) and the files it names
`models`	`{scout, reviewer, verifier, report, post}` with the aliases `haiku`, `sonnet`, `opus`, `inherit` (the session model)
`dimensions`	replace the mode’s defaults: strings, or `{key, title, questions}`
`votes`	3 for a third verification lens (existing test coverage); default 2 in full, 1 otherwise
`allowCommands`	the project’s read-only checks the reviewers may run (`go vet ./...`, a linter). The test suite, builds, formatters and servers stay off
`post`	with `pr`, post the report as a PR review comment — only when the user asked for that

The result holds verdict, report (Markdown), findings (blocking — and what to feed the next delta run as previous), followups, previous_status (delta), dropped (refuted, with reasons), nits, agents, tokens.

Every reviewer works under the same brief: read-only git; code graph first, grep as fallback; the project’s conventions and, with OpenSpec, the active change’s proposal, spec and tasks; a fresh read at the reviewed commit behind every quote; nothing run beyond allowCommands.

The stop rule

The first week of using it produced four full runs on one fix, about five million tokens, each round finding real edges of the previous round’s code — most of it in lines the change had not touched. The tool was right every time; the loop was wrong. Hence:

git status must show nothing new after a run. Anything else is a reviewer that broke its brief: revert it.
Fix the blocking findings (and, in delta, any previous finding not confirmed fixed) on the branch that owns the code, with a test where the finding names one.
Follow-ups do not loop. Record them in the change’s notes and the PR description. Fix one in the same batch only when it is a Critical the change made reachable, and say so.
Re-run in delta mode with the previous findings. Stop when the verdict is APPROVE. After at most two deltas, stop anyway and hand the PR to a person: a third round of machine findings on the same lines means the design, not the code, needs a look — run plan on the next attempt.
Once every fix is in, one full run with pr: N over the whole PR, then the human review.
Record every round — mode, agents, tokens, finding → fix → commit — and paste the report table into the PR description.

Refuted findings are in the report with the refuter’s reason. Read them; a refuter can be wrong too, and a human disagreement reopens one.

Where it lives

.github/skills/coograph-ultra-review/ — SKILL.md and workflow.js, plain JavaScript on the Workflow tool’s API. The initialiser copies it into every project; the sync script keeps it current; the plugin ships it as /coograph:coograph-ultra-review. The retro’s defect rule counts an ultra review as a review. See Workflow for where it sits in Plan → Propose → Apply → Review → Archive.