review-pr
Skill0 starsChanged 3 days agoMITView on GitHub
Use when asked to review a pull request or branch — "review PR 42", "review this branch", "look over my changes", "deep review" for the exhaustive pass, or names one area to review — and for the later asks on a review already produced — post, stage, apply, or reply-and-resolve its threads. GitHub, Azure DevOps, and GitLab.
185 other projects use a version of this.
Adopted by
Most recently taken up by
- torrust/torrust-trackertheir own version, first seen Nov 16, 2026
- Wendor/teapod-streamtheir own version, first seen Nov 16, 2026
- testcontainers/testcontainers-javatheir own version, first seen Nov 16, 2026
- chuckplayer/claude-agent-packtheir own version, first seen Nov 16, 2026
- ayoubben18/ab-methodtheir own version, first seen Nov 15, 2026
- connext-solutions/flowctltheir own version, first seen Nov 15, 2026
Used with
Projects with it also use diagnose-ci-failures, review-delta and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
zerx-labSkilldiagnose-ci-failures
Diagnose CI failures for a PR using the GitHub CLI, extract error logs, and generate a plan to fix them. Use when the user asks to check CI status, pull CI issues, triage test failures, or investigate PR build failures.
Also in 3 projects that use this
n24q02mSkillreview-delta
Review only changes since last commit using impact analysis. Token-efficient delta review with automatic blast-radius detection.
Also in 3 projects that use this
GeiserXSkilldocs-loop
Use when the user asks to audit docs, check documentation for stale claims, or verify docs against the code.
Also in 3 projects that use this
GeiserXSkillfull-loop
Drive a repository to done with sergio-loop, then keep improving it with refine-loop at a descending theta. Use only when the user explicitly invokes full-loop.
Also in 3 projects that use this
n24q02mSkillbuild-graph
Build or update the code review knowledge graph. Run this first to initialize, or let hooks keep it updated automatically.
Also in 3 projects that use this
- +7 more from GeiserX
Other versions185 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 185
- denoland/deno★ 109ksame name
- ToolJet/ToolJet★ 41ksame name
- remix-run/remix★ 33ksame name
- tirth8205/code-review-graph★ 33ksame name
- alpinejs/alpine★ 32ksame name
- nrwl/nx★ 29ksame name
- PrefectHQ/fastmcp★ 29ksame name
- jlowin/fastmcp★ 29ksame name
- livewire/livewire★ 24ksame name
- microsoft/fluentui★ 20ksame name
175 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository20 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- addressing-review-feedbackSkill
- budgeting-agentic-workSkill
- coordinating-sessionsSkill
- delegating-to-subagentsSkill
- explaining-changes-visuallySkill
- git-syncSkill
- implementation-gatesSkill
- implement-planSkill
- landing-merged-workSkill
- maintaining-project-memorySkill
- plan-featureSkill
- reporting-defects-upstreamSkill
- tracking-open-asksSkill
- verifying-before-sendingSkill
- writing-code-commentsSkill
- writing-commit-messagesSkill
- writing-for-audiencesSkill
- writing-plan-docsSkill
- writing-pr-descriptionsSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 5 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 178 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 32
Every finding of the earlier round, posted or not, gets a status at the new head: fixed, still present, or gone with its code.
- Distinctive: line 60
No such task exists: the deferral itself is the gap.
- Very specific: line 67
Treat TODO comments as intentional future work — do not challenge them.
- Distinctive: line 110
If the user names an area to review explicitly, honor that on top of the triage.
- Very specific: line 138
Personally grep-verify: every surviving finding's mechanism and file:line anchor against the pinned SHA before writing the findings file — …
- Distinctive: line 139
Anchor validation: run the platform reference's anchor rules — both platforms constrain which file an inline comment may anchor to (GitHub …
- Very specific: line 143
Write the findings file only once every dispatched axis agent has reported (verifying-before-sending owns that gate: a closing report that …
- Distinctive: line 180
No key holds a local path: clones move, and the folder must read the same from any of them.
“Common” is measured: kept by at least 6 in 10 of the 178 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Review PR — Two-Pass Multi-Axis Review (review + verify; post or apply only on request)
One invocation, two passes, no posting. Pass 1 is a multi-axis review: parallel single-axis subagents against a pinned worktree, plus a mutation-testing agent in its own worktree. Pass 2 is fresh-eyes verification: by default ONE clean-context subagent tries to refute every finding and sweeps for misses; a deeper blind-re-review + isolated-skeptics mode runs only when the user explicitly asks for a deep review or the repo-nuances memory pins it. Findings go to a findings file — not into chat. Posting and applying (section 6, references/posting-and-applying.md) happen only when the user asks in a later message.
0. Platform
Detect from git remote get-url origin and read the matching reference before starting (it defines PR discovery, dedupe mechanics, anchor rules, and posting):
github.com→references/github.mddev.azure.com/visualstudio.com→references/ado.md- gitlab.com, or any host
glab auth statusrecognizes (self-hosted GitLab often has no "gitlab" in its hostname) →references/gitlab.mdThen verify the platform CLI is present and authenticated (gh auth status;azor$AZURE_DEVOPS_EXT_PATper the ADO reference;glab auth status) before any review work starts — a missing login should cost the user one setup instruction now, not a dead review half an hour in. - Any other host (Bitbucket, Gitea, …): no reference exists — say so plainly. Review the local branch diff against its merge-base with the default branch (sections 2–5 are platform-neutral), skip the PR-thread dedupe, and state that posting and disposition are unsupported on this platform. Never improvise API calls from general knowledge — the references exist because real mechanics diverge from the obvious.
1. Scope & setup
- Check project memory first for a
review-repo-nuancesentry — it records this repo's gate commands, mutation-axis test command, bot reviewers to dedupe against, PR conventions, any depth pins (e.g. deep-mode Pass 2, no small-diff shortcut), and — whenimplement-planleft one — the location of the branch's executed gates record (plan path, branch, the SHA the gates ran at). If it doesn't exist, discover those from the repo's CLAUDE.md / CI config during the review and save such a memory (+ MEMORY.md index line) before finishing. - Never switch the user's branch. Identify the PR first via the platform reference — the user may give a branch, a PR number, or a URL — and record its head SHA and target branch. Then
git fetch origin <branch>for the PR's head branch (works for branches never fetched). Every later step pins to the head SHA. - Diff =
git diff $(git merge-base origin/<base> <head>)...<head>where<base>is the PR's target branch (default branch if no PR exists). Read the PR body too: claims it makes about content ("includes X") are auditable and sometimes stale. - A later round reviews only what changed since the round before it. Look for earlier rounds in the request's folder (§5) and, for a request, in the folder of the branch it was reviewed from before the request existed. Where one exists, the newest round's
reviewed_shais where this round starts, and by default it reviews only the delta from there:- Fetch the earlier commit if it is missing (
git cat-file -e <old>). Then replay the change as it stood onto today's merge base and diff that against the head:R=$(git merge-tree --write-tree --name-only --no-messages --merge-base=$(git merge-base origin/<base> <old>) $(git merge-base origin/<base> <head>) <old>); its first line is the replayed tree (T=$(printf '%s\n' "$R" | head -1)) and any further lines name the files the replay conflicts on, and the delta isgit diff $T <head>. Each side is taken from its own merge base, so a merge of the base branch into the request adds nothing to the delta, where a plaingit diff <old> <head>would carry the whole merge in. Files the replay conflicts on are reviewed in full. - The readers still read the surrounding code and the whole change; what they grade is the delta. The mutation axis runs only where the delta changed tested logic.
- Every finding of the earlier round, posted or not, gets a status at the new head: fixed, still present, or gone with its code. A posted thread marked resolved is checked against the code, never trusted (step 6's rule).
- The round is written beside the earlier one as the next file, with
kind: delta-review,previousnaming the earlier file by its path under the repository's folder (branch-feat-x/r3-<sha7>.mdwhen it sits in the branch's folder),roundone more than that file's, andscopethe range reviewed (<old7>..<head7>). - It runs in full instead, saying why in the hand-off, when the earlier round was scoped (its
scopeis notfullor a range), when its commit can no longer be fetched, when the replay cannot run (--merge-baseneeds git 2.40 or later), or when the user asks for a full review.
- Fetch the earlier commit if it is missing (
- When the PR's author is a bot or AI pipeline (a fix agent, a scan bot, a generated PR), the review gains three checks:
- Verify the stated premise. Check the issue's or body's cited location and quoted observation at the branch point (
git show $(git merge-base origin/<base> <head>):<file>; the moving tip of base may have changed since the PR forked) before evaluating the fix. Real cited paths make a false observation read as plausible. A premise that fails verification is a major finding recommending the PR not merge as-is; skip fix-level review of that hunk, since the fix acts on content that is not there. - Sweep for tool exhaust: bytes outside the stated scope.
git diff --word-diff-regex=.catches single-character edits inside long opaque strings; decode every touched encoded payload rather than eyeballing it, since one flipped character inside one reads as unchanged. Artifacts the tool left riding the diff (telemetry files, run logs) are findings whose fix is removal; section 2's generated-artifact rule draws the line between exhaust and an artifact the PR deliberately carries. - Check in both directions. Generated issues are not uniformly fabricated; one was verified real and fixed. Never trust, verify.
- Verify the stated premise. Check the issue's or body's cited location and quoted observation at the branch point (
- Dedupe against existing review surface first: pull existing comment threads (platform reference has the mechanics) from all authors — humans and bots. Don't re-raise what's already raised; verify that "resolved" items are actually fixed in the current code — a resolved thread with the bug still present is a top finding.
- Create two detached worktrees at the head SHA in the session scratchpad:
review-<id>-readfor all reading agents,review-<id>-mutfor the mutation agent (it edits files — it never shares a tree with readers).<id>= the PR id if one exists, otherwise the branch name with/replaced by-; the same<id>names the findings file where §5 falls back to the clone. Remove both worktrees (git worktree remove --force) when done.
2. Finding format (all passes)
Shape of a finding
- Issues only — no praise, no confirmed non-issues in the final findings or in posted comments (the findings file's Pass 2 verdict log does record REFUTED entries with reasons — that's its job; chat may mention non-issues).
- Grade major / medium / minor. Each finding: Title /
file:line(at the head SHA) /Problem:/Suggestion:— one problem, one single best fix, no hedged fallbacks (a fork is allowed only when the right fix depends on author intent). When the fix is an exact replacement of a small run of contiguous lines, the Suggestion records the replacement snippet, the exact replaced line range, and the original content of those lines (the posting reference's staleness check compares against it). At posting time it becomes a one-click appliable suggestion block if the rules inreferences/posting-and-applying.mdallow it (they don't for relocated anchors or large replacements). - Anchors are pinned; proposed text is not (learned from a real PR review). The finding's own
file:linecites the head SHA and is re-validated at posting — line numbers are correct there. But text a Suggestion proposes to add to a durable artifact (spec, design note, README, wiki, plan prose) outlives every pin: in that text, reference by stable identity — a quoted fragment, a section or heading name, an artifact id, a symbol name — never bare line numbers (they drift on any unrelated edit, with nothing to flag it) and never SHAs of unmerged commits (a squash erases them). One admissible exception: a line-numbered enumeration that explicitly names the commit it was verified against — snapshot semantics, consumed against that state, not maintained. (writing-plan-docs' reference rules own the general anchoring discipline; this bullet carries the review-specific deltas.) - Example of the shape (invented): Medium — Retry loop swallows the final error /
src/sync/push.ts:142/ Problem: the catch rethrows only whileattempt < max, so the last failure is silently dropped and the sync reports success — a consumer polling for completion sees a green run with no data. / Suggestion: rethrow unconditionally once attempts are exhausted; the caller's telemetry already distinguishes retry exhaustion from first-try failure. - Tone: polite, mechanism-first, no editorializing ("pure waste", "rot", "tautological" banned); acknowledge documented-deliberate decisions before questioning them; conventions phrased as "the repo's convention asks"; the goal is fixes, not a verdict.
- Walk each finding through its mechanism: what happens → why it matters → the fix. The reader must not need follow-up questions (
writing-for-audiencesowns the general rule; this is its finding-form application). - Write comment bodies human-first, never as one chained sentence (learned from a real PR review). A Problem stacking 3+ facts renders them as a bulleted list. A Suggestion with more than one action becomes a numbered list ("Suggestion — two edits:"), one action per item. Multi-step procedures are numbered steps, never arrow chains (A → B → C). Test: the author should be able to act on each item without re-reading the sentence it came from. Fixing an already-posted comment: edit in place (
gh api -X PATCH .../pulls/comments/<id>/ ADO thread update), no correction trail, and record the edit + timestamp in the findings file. - Each finding must be self-contained and actionable. No deferrals to "a later PR". No offers of the user's help.
- Write in the user's voice — everything posted goes out under their account and must read as theirs.
Grading rules
- An absence claim names its authority, and the search has an order. A finding that something is unbounded, unvalidated, uncovered or unreachable states three things: the layer that would impose the constraint, what that layer says, and the range you verified. Search in order — the repo's own ticket, plan and spec first, then its guideline docs, then the code of the tier below, and only then library docs and remote services. The nearest authority is the cheapest to read and the most binding; the furthest is the one you cannot reach, and a finding that stops there has found the limit of its own search rather than a limit of the system. Where the reviewed layer deliberately declines a check, the delegation is the finding's subject, not the absence. Reading the authority re-grades findings as often as it retires them (learned from a real PR review).
- Resolve a delegation before grading what it defers. The rule above makes the delegation the finding's subject; this one says open it. When the diff, its plan, or its spec hands work to another task ("a follow-up owns this", "the X task"), look that task up in the tracker and read what it claims to own. The plan and spec are already open in the worktree; the tracker is a separate lookup, and it is the step reviewers skip. What you find decides the finding:
- No such task exists: the deferral itself is the gap.
- It owns exactly what was deferred: drop the gap and keep only what is wrong regardless of that task.
- It owns more than the deferral admitted: this change has shipped part of that task. File one finding for the shipped part: its Problem lists every gap inside that part as a numbered symptom, and its Suggestion is one action, hold that part back until its owner lands it. The gaps appear only as symptoms there, never as their own findings with a local fix.
- The tracker is unreachable: say so in the finding and grade the deferral as unverified.
- A finding that cites a written convention states the surrounding file's compliance first — how many of the file's existing exports, handlers or callers follow the rule being cited. Where the file had such code before the change and none of it follows the rule, the file has never followed it, and that is the repo's own drift: file it once, as one minor finding anchored at the file, its Suggestion addressed to the repo (bring the file to the convention, or amend the convention), and nothing against the changed lines — a finding that asks one author to be the first to comply files the repo's debt as their defect. A file the change creates has no neighbours to excuse it and is graded against the convention as written. The axis-reviewer contract carries the same rule for dispatched axes, since an agent cannot load this skill; this statement owns it.
- A recorded hold constrains the Suggestion. Where the plan already records how a gap is held until its owner ships (a pointer comment rather than a local fix), the Suggestion may not ask for more; that would ask the author to override a recorded team decision (learned from a real PR review).
- Never flag AI-attribution trailers (
Co-Authored-By: Claude ..., "Generated with" footers) in a teammate's commits or PR body — a no-AI-attribution convention, where the user keeps one, governs their OWN git artifacts only. - Treat
TODOcomments as intentional future work — do not challenge them. Omit locale files from the review. - Generated plan documents are read-only context, never a finding target (learned from a real PR review): a
docs/plans/**artifact — typically an HTML plan emitted by the planning tool — is produced upstream of the diff, so a defect in it is fixed in the generator, not by the PR author. Read it to learn what the implementation was supposed to do and audit the code against that intent; never raise a finding against the plan file itself, and never count its own inconsistencies as diff defects. The same rule applies to any other deliberately produced tool-generated artifact the PR merely carries along; accidental tool exhaust riding the diff (telemetry files, run logs) is instead a finding whose fix is removal — see section 1's bot-author item. One exception: an executed verification record wherever the PR carries it — in the plan, in another document in the diff, or in the description (an implementation-gates mutation table) is a claim about this branch's tests — audit it per section 3, and a record the audit contradicts is a valid finding.
Grouping — one thread per problem, not one per observation
Default: merge findings that share an anchor file, a fix, or a defect class into a single finding. A reviewer who files every observation separately hands the author the triage work; grouping does it once, on the side that already has the evidence. It is also the honest shape — a live defect and the test gap that hid it are one problem, and split apart the second reads as unrelated cleanup.
- A grouped finding's
Problem:is a numbered list, one item per instance, each keeping its ownfile:line. ItsSuggestion:is a numbered list, one edit per item — the numbered-list rule above, applied at group scale. - Anchor the group to its most significant member's
file:line. The numberedProblem:list already carries every member's true location — the same convention relocated anchors use — so a group never needs a PR-level home for spanning files (diff-membership routing is the posting reference's separate rule). - Never group across severities. A major or medium riding inside a bundle of minors loses the grade the author sorts by; group within a band only.
- Never group to shorten the list. Findings whose fixes land in different files and would be acted on independently stay separate even when they share a theme. The test: would one author, in one sitting, make all the edits as a single change? If not, they are separate.
- Findings that would each carry a suggestion block stay separate — a comment applies a block only over its own anchor, so a grouped thread keeps at most one, and a one-click apply is worth more to the author than a shorter thread list.
- Grouping happens at §4's final merge, after Pass 2 verdicts land — the draft the verifier receives stays ungrouped. Merging two findings hides whichever one a skeptic would have refuted.
Opt out when the user asks ("one thread per finding", "don't group", "ungrouped"), which is also the right shape when the review will be dispositioned item by item.
Compact — planned in every review, applied only when the user asks ("post compact", "compact", "fewer threads"). Compact lifts two limits of the default and keeps every other: findings of one defect class merge even when their fixes land in different files, and findings that would each carry a suggestion block merge too. A defect class is the kind of work one pass fixes — docs that misdescribe the code, rules no test pins, departures from the repo's conventions, input the code should refuse. The test moves from location to title: the title states one claim that is true of every member, and a title that needs "and also" is two threads. Severity bands still never mix, and a major or medium merges only with another instance of the same defect. Work the compact packing out at §4's final merge, while the findings are in context, and record it in the findings file as a table — thread title, grade, members (final findings, or numbered items of one), anchor — beside the default list, never in place of it: the bodies are written once, in default form, and a compact thread is assembled from its members' numbered items at posting. The packing is a plan, so it costs a table now and no second analysis later. What happens to the members' suggestion blocks, and how a compact thread is dispositioned, is the posting reference's.
3. Pass 1 — multi-axis review
For small diffs (roughly < 300 changed lines) review inline yourself (the mutation axis still applies if tested logic changed). Otherwise, dispatch parallel single-axis subagents, each given the section-2 format rules, the read worktree path, and the head SHA — which its report must name back (a report that doesn't name the commit is unverified: re-dispatch that axis once; if still missing, discard its findings). Every dispatch in this skill — axes, mutation agent, Pass 2 verifier — follows delegating-to-subagents for the machinery it owns: the file each report goes to named in the spawn prompt, with a reply of that path alone, telling the long-running mutation agent to script its sweep and write running results to disk, and the liveness rules before taking a silent axis over. Where the plugin's axis-reviewer, refute-verifier, and mutation-tester agent types are available, dispatch with them — they carry this skill's reviewer, skeptic, and mutation contracts, so the spawn prompt only needs the axis, worktree path, pinned SHA, scope, and the file the report goes to (plus the test command for the mutation agent).
- Correctness — logic bugs, edge cases, argument/flag handling, cross-platform assumptions.
- Security / input handling — injection, traversal, credential leakage, unvalidated input. Only when the diff touches servers, child processes, auth, or file IO. Calibrate: a loopback-only dev tool's flaw is minor, not major.
- Test quality — fixture honesty (could anything the fixture does fail the test?), non-default config values, coverage gaps, CI wiring (do the new tests actually run from the root pipeline?). Normally folded into the mutation axis — a reader guessing which tests are weak duplicates what mutation measures. Dispatch it separately only when tests changed but no source did, or when CI wiring is the question.
- Doc-vs-code audit — when the PR carries docs/specs/READMEs claiming what the code does: verify every claim against source; flag documented-but-absent and load-bearing-but-undocumented. Docs rot faster than code and nothing else checks them. Sweep doc-vs-doc and comment-vs-comment too: a contradiction between two statements is an unresolved factual question about the system, not a tidiness defect. Never write the finding as "these two disagree, please align them" — that offers a choice between strings and says nothing about which describes reality. Determine which is true (empirically, if the system is reachable), lead with the substantive consequence, and if the repo cannot settle it, say so and name the check that would. Weight a contradiction higher when the two sides imply different runtime behavior — which endpoint, which identity, which order — than when they differ only in wording; the first is a live defect wearing a documentation costume. When the diff promotes a statement across documents — chat into a spec, a spec into a wiki, a rule into CLAUDE.md — check the promoted imperative against the original verbatim, not the intermediate copy: a boundary condition dropped at one hop reads consistent at every later hop, so each downstream reviewer sees only a faithful paraphrase of the tier before. Compare against the earliest tier you can reach; when the true original (a chat) is unreachable, report that hop as unverified rather than passing it. Check qualifiers in both directions: a dropped condition survives as a false absolute, and an added condition the mechanism does not require — a tool name, a team, a location — silently narrows the rule so it stops firing on cases it should cover.
- Repo conventions & gates — the target repo's own CLAUDE.md rules, guideline-doc trees, and CI gate commands (the repo-nuances memory from section 1 records where these live); this axis may install deps and run those gates in the read worktree only (untracked artifacts only, never edits — each check in its non-fixing form, since a lint script that chains fixers edits the tree under the other readers).
Axis triage — choose from the diff, never run the set
Running every axis on every diff is the default failure mode, and it is expensive: on a 750-line branch, eight agents cost more than the findings were worth, and most of the overlap was redundant reading. Axis diversity beats axis count — five reviewers reading the same way find the same bugs five times.
Choose by trigger, and state the chosen axes and why in one line before dispatching, so the cost is visible and the user can add or drop one (budgeting-agentic-work owns the general price-the-pass rule):
| Axis | Dispatch when |
| Mutation | tested logic changed — always first, and the only axis that measures rather than reads |
| Correctness | non-trivial logic, control flow, or arithmetic changed; skip for renames, config, copy |
| Doc-vs-code | the diff carries docs, specs, or a plan rewritten as a shipped spec, making behavioral claims |
| Resource / security | child processes, auth, file IO, network, or untrusted content reaching logs |
| Repo conventions | diff over ~400 lines, or it touches a subsystem with its own CLAUDE.md — below that, just run the gates yourself, which is cheaper than an agent reading the guideline tree |
| Test quality | tests changed but source did not (otherwise the mutation axis covers it) |
If the user names an area to review explicitly, honor that on top of the triage. If the user asks for a deep or exhaustive review, run the full set.
Mutation-testing axis (own worktree, runs alongside the readers)
Highest-yield axis for any PR that adds or changes tested logic — it finds correct-but-unpinned code no reader can see.
If an executed implementation-gates record exists — in the branch's plan, in any other document the diff carries, in the PR body, or at the gates-record pointer in the repo-nuances memory — (a mutation table naming each edit and the test that killed it), audit it instead of re-buying it. Run the green baseline first, as below. Then re-apply the recorded mutations one at a time against that baseline and watch them fail — every row where the record holds twelve or fewer, since one row costs one suite run — and above that a draw made across the record rather than from its opening rows, with the rows it did not reach named in the findings as unchecked. A row nobody re-applied is unchecked rather than confirmed: nothing in the record marks which of its claims the tree contradicts, and a fresh mutation elsewhere cannot contradict a claim it never applied. Then spend fresh mutations on changed lines the record does not cover — where a record executed at an older SHA covers only lines unchanged since that SHA. A recorded mutation whose anchor no longer matches is staleness, not dishonesty: re-sweep those lines fresh, no finding. A recorded mutation that applies cleanly and survives IS a finding — a written verification claim the tree contradicts.
For the fresh mutations, dispatch the mutation-tester agent with the mutation worktree, the pinned SHA, the test command, the changed lines in scope, and the file its report goes to; it carries the protocol (implementation-gates' Gate 1 owns its statement — baseline first, one mutation at a time applied with a unique old_string, count and duration compared to baseline, revert and clean check between, survivors screened for equivalence, all-killed re-checked). Without the agent type, run that protocol yourself in the mutation worktree from the Gate 1 text. Review-specific: aim for 10–15 mutations at decision points, and every non-equivalent survivor is a finding — exact before → after, the bug class it simulates, and the specific missing assertion as the suggestion.
Grade survivors as test gaps, not live defects: caps at medium (core outputs, gates, stats primitives), else minor.
4. Pass 2 — fresh-eyes verification, then personal checks
Consolidate and dedupe axis findings into a draft (axis reviewers and the mutation agent often flag the same gap — merge, keeping the mutation's concrete evidence). Then verify:
Run the verifier by default. Skip the dispatch only when BOTH hold: the diff was small enough to review inline (section 3's ~300-line shortcut) AND Pass 1 produced no major finding — then grep-verify the findings yourself against the pinned SHA. Finding count alone never gates the dispatch: a quiet Pass 1 on a large diff is where the sweep matters most, because a low count cannot distinguish a clean diff from a review that missed — on such a run the subagent's job is mostly the sweep, so dispatch it even with zero draft findings. The personal check below is required either way.
Default: dispatch ONE clean-context fresh-eyes subagent with the draft, the read worktree path, the pinned head SHA, and the file its report goes to (it must not redo section-1 setup). Prompt it to refute each draft finding, the same stance deep mode gives its skeptics. A verifier asked to "check" tends to confirm, and re-derivation only protects when the agent is hunting for the hole. Absence claims are its highest-yield target: for those the refutation is to go and find the layer that supplies the missing constraint, in §2's search order; for a gap the plan or spec defers to another task, it is to open that task in the tracker and compare what it owns with what was deferred (§2's delegation rule). For every draft finding it attempts to break the claimed mechanism against source and returns CONFIRMED (the refutation failed — cite the evidence that resisted it) / REFUTED (with evidence) / ADJUSTED (severity, anchor, scope). Then it sweeps the whole diff once more for what all axes missed. Both directions matter — past passes killed false positives AND found real bugs every time.
Deep mode — only when the user explicitly asks for it ("deep review", "thorough", "paranoid") or the repo-nuances memory pins it for the repo: replace the single verifier with two isolated jobs, dispatched concurrently, each naming the file its report goes to:
- Blind fresh re-review (miss check): ONE subagent given the sections 1–2 scope/format instructions, the read worktree path, and the pinned SHA but none of the draft — a verifier that has read the draft is anchored by it; this one hasn't. It reviews from scratch and returns its own graded findings; those absent from the draft are additions and go through the same skeptic check before acceptance.
- Isolated skeptics: one skeptic subagent per draft finding, seeing only that finding plus the relevant code, prompted to refute it; verdicts as above. Findings sharing a code locus (same file AND same function / overlapping lines) may share one skeptic — max 3 per group, a separate verdict per finding, and it may recommend merging facets of one issue. Never group by theme, axis, or severity — a skeptic must never see the review's breadth.
Then merge in the main conversation (both modes):
- Drop REFUTED findings; re-grade where an ADJUSTED verdict is convincing. Sweep/blind-review additions join the final list only after surviving verification — in deep mode the skeptic check; in default mode the personal grep-verify below is the additions' gate (re-derive the mechanism yourself, not just the anchor).
- Personally grep-verify every surviving finding's mechanism and
file:lineanchor against the pinned SHA before writing the findings file — subagent citations are necessary but not sufficient. - Anchor validation: run the platform reference's anchor rules — both platforms constrain which file an inline comment may anchor to (GitHub refuses an out-of-diff anchor; ADO accepts it and mis-renders it), and findings on untouched files route to PR level per the posting reference.
5. Output — findings file, not chat
Write the findings file only once every dispatched axis agent has reported (verifying-before-sending owns that gate: a closing report that lands after the conclusion means the conclusion was premature).
The file goes to one folder outside every clone, never into the clone: there it sits in the author's change list beside their own work, the clone's hooks and formatters reach it, and it goes when the clone goes, while a later session that wants it back (to post it, apply it, or review the request again) has no fixed place to look. The path is <root>/<repo>/<request>/r<N>-<sha7>.md:
<root>is$DELIVERY_SKILLS_REVIEW_DIRwhere that is set, otherwise${XDG_STATE_HOME:-$HOME/.local/state}/delivery-skills/review-pr.<repo>is theoriginremote's host and path, percent-decoded and then lowercased (a project the remote spellsField%20Opskeys asfield ops), with no scheme, user, port or.git:git@github.com:Acme/Tickets.gitkeys asgithub.com/acme/tickets. A host that is an SSH alias is resolved first (ssh -G <alias> | sed -n 's/^hostname //p'), so a second clone of the repository, or a clone that moved, reaches the same folder. An Azure DevOps remote keys asdev.azure.com/<org>/<project>/<repo>whichever URL form it uses. With no remote,local/<the clone's directory name>.<request>ispr-<n>, orbranch-<name>with/replaced by-for a branch reviewed before any request exists.<N>is one more than the highest round already in that folder, 1 for the first;<sha7>is the reviewed head's short SHA.
A path the user names for the findings wins over all of this. Where the folder cannot be created or written, the file falls back to review-findings-<id>.md in the clone's root, untracked, and the hand-off says that it fell back and why.
The file opens with frontmatter, then a title line linking the request (or naming the branch). The keys extend the ones the folder's earlier files carry, under the same names, so the next round and a later pass over many reviews read old files and new alike:
---
repo: github.com/acme/tickets # the folder key above
pr: 42 # null for a branch review
pr_url: https://github.com/acme/tickets/pull/42
branch: feat/close-ticket # the head branch
base: main # the target branch
title: Close a ticket from the queue
author: mara-k
reviewed_sha: <the full head SHA> # posting-time re-verification keys off this
merge_base: <the full SHA>
round: 1
previous: null # the round this one follows, by its path under <repo>, e.g. pr-42/r1-<sha7>.md
kind: review # delta-review for a later round (§1)
scope: full # the area the user named, or <old7>..<head7> for a later round
depth: default # or deep
reviewed_at: <ISO 8601 time>
plugin: <this plugin's name and version>
model: <the model id>
findings: { major: 0, medium: 3, minor: 4 }
posted: null # the posting step rewrites it
---No key holds a local path: clones move, and the folder must read the same from any of them. Sections:
- Earlier findings — a later round only: each finding of the round it follows, by its title and grade, with its status at this head and the evidence for it.
- Pass 1 findings — the draft list, graded.
- Pass 2 — per draft finding: CONFIRMED / REFUTED / ADJUSTED with the verifier's reason; then the additions (from the sweep, or the blind re-review in deep mode) and whether each survived verification.
- Final findings — the merged list, organized by severity, then §2's compact packing table.
In chat, report only the file's absolute path and counts (e.g. "6 confirmed, 2 refuted, 1 adjusted, 1 added"), the thread count each way ("16 threads by default, 12 compact"), plus a one-line index of the grouped findings — title and grade only, no bodies, so the user can see the shape of the review and redirect it before anything is posted. A later round also names the range it reviewed and counts the earlier findings by status ("3 fixed, 1 still present, 1 gone with its code"), or says why it ran in full. When this write created the <root> folder, add one line saying that reviews now live there, outside the clone, and that DELIVERY_SKILLS_REVIEW_DIR moves them. A findings file inside the clone — the fallback, or a path the user named there — is exposed to the repo's own automation: a pre-commit hook that stashes untracked files takes it out of the tree on the author's next commit, and the restore is the step that gets skipped — a check that fails between the stash and the pop aborts the commit with the file still in the stash, and a pop that conflicts leaves it there too — so a hook that stashes is never reported as safe because it also restores; and a formatting gate that runs over every file can block their next push on it. Check the repo's hooks and gates for either (the repo-conventions axis has read them), and where one exists say so beside the path in the hand-off, so the author moves or excludes the file before it costs them a commit. Do not restate the findings themselves in chat. Finish with §7's one-line note of what the user can ask for next.
6. Posting and applying (later asks only)
Posting findings to the PR and applying them to the tree are separate user requests — never automatic after a review, and often made in a fresh session, which finds the review as the newest round in the request's folder (§5) unless the user names another file. When the user asks to post, stage, or apply, read references/posting-and-applying.md and follow it; on GitHub and Azure DevOps it posts through the bundled post-review.py (references/posting-script.md), and it carries the re-verification and staleness checks, the pending/staged mode, the thread and suggestion-block packaging rules, the reply-and-resolve discipline, and the apply-mode protocol (every new test must fail against pre-fix code first).
7. Modes — and telling the user they exist
Every mode below is off unless the user asks. The failure this section exists to fix is not that they are undocumented: it is that they are documented for you and invisible to the user, who cannot request a mode whose trigger phrase they have never seen. A capability nobody knows about is a capability that does not ship.
| Mode | The user says | What changes |
| Deep review | "deep", "thorough", "exhaustive", "paranoid" — or a repo-memory pin | Full axis set instead of triage (§3); Pass 2 becomes a blind re-review plus isolated skeptics per finding, locus-sharing per §4 |
| Scoped review | names an area, file, or concern | That scope is honored on top of the triage, never in place of the mutation axis (§3) |
| Full review | "review it all again", "full review" | A later round reviews the whole change instead of what changed since the round before it (§1) |
| Ungrouped | "one thread per finding", "don't group" | Disables §2's grouping default |
| Compact | "post compact", "compact", "fewer threads" | Posts from the findings file's compact packing table: one defect class is one thread, across files; multi-member threads lose their one-click suggestions (posting reference) |
| Post | "post" | Publishes the final findings (§6) |
| Staged post | "hold it", "I'll submit it myself" | Findings staged invisibly where the platform supports it; where it does not, say so plainly and post nothing |
| Apply | "apply", "fix these" | Findings become edits on the branch, each new test failing against pre-fix code first (§6) |
| Disposition | "resolve", "reply to the threads" | Reply-and-resolve against the findings file, verifying each fix actually landed (§6) |
| List reviews | "list my reviews", "open the last review of PR 42" | Lists the repository's folder (§5), newest round first, with each file's request, round, reviewed commit, counts and whether it was posted — or opens the one named |
Name the applicable modes in the closing message, in one line — not a menu, and only what the user could sensibly want next. After a review that is post, post compact, apply, or a deeper pass; after posting it is apply or disposition. When a mode the user asked for is unavailable on the platform, say which and why rather than silently doing something else.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

