pr-review-loop
Skill331 starsChanged 4 months agoApache-2.0View on GitHub
Use to run a continuous review sweep over open contributor PRs in phase.rs. The skill is a thin orchestration layer over scripts/pr_review.py: discover candidates, detect stale reviews/follow-ups, dispatch review-engine-impl for PRs that need judgment, and delegate authorized merge handling to pr-contribution-handler.
18 other projects use a version of this.
Adopted by
Most recently taken up by
- ksprashu/agent-skill-forgetheir own version, first seen Nov 8, 2026
- tloncorp/tlon-appstheir own version, first seen Nov 2, 2026
- gabonio/agent-operator-toolkittheir own version, first seen Nov 1, 2026
- wollemiahq/skillstheir own version, first seen Nov 1, 2026
- vrodokanakis/claude-skillstheir own version, first seen Oct 25, 2026
- tankcdr/cdr-kittheir own version, first seen Oct 20, 2026
Other versions18 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 18
- basicmachines-co/basic-memory★ 4.6ksame name
- tloncorp/tlon-apps★ 109same name
- fagemx/gstack-game★ 68same name
- fagemx/edda★ 36same name
- xpepper/pr-review-agent-skill★ 6same name
- GavinGreenwood/agentic-workflow-template★ 5same name
- ksprashu/agent-skill-forge★ 3same name
- adevra/claude-pr-review-loop★ 2same name
- typeweaver/skills★ 2same name
- voundbrand/overnight★ 2same name
8 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 repository33 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-ai-feature-policySkill
- add-card-data-pipelineSkill
- add-engine-effectSkill
- add-engine-variantSkill
- add-frontend-componentSkill
- add-interactive-effectSkill
- add-keywordSkill
- add-replacement-effectSkill
- address-reviewSkill
- add-static-abilitySkill
- add-triggerSkill
- ai-duelSkill
- audit-card-parsingSkill
- batch-mechanicsSkill
- bug-coverage-classifierSkill
- bug-triageSkill
- card-testSkill
- casting-stack-conditionsSkill
- changelogSkill
- engine-implementerSkill
- engine-plannerSkill
- oracle-parserSkill
- parser-velocitySkill
- pr-contribution-handlerSkill
- pr-flow-auditSkill
- project-referenceSkill
- retrain-ai-weightsSkill
- review-engine-implSkill
- review-engine-planSkill
- ship-commitsSkill
- unlock-setSkill
- validate-cr-annotationsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. 0 are common, 10 are distinctive, and 6 are very specific to this project.
0
Common
Most of the 16 edited versions we read keep these.
10
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 30
Use the CLI from the repo root:
- Distinctive: line 55
Import legacy state once:
- Very specific: line 92
Check both surfaces, and read what actually matched before acting — a bare rg cursor hits WordCursor and other identifiers:
- Very specific: line 123
After any delegated approval/label/enqueue operation, independently run gh pr view <PR> --json labels and verify the expected type label …
- Very specific: line 132
Before removal, confirm no agent, Tilt instance, or command still uses the directory.
- Distinctive: line 135
Before reporting the sweep complete, confirm every checkout created for it was removed or explicitly retained with a reason.
- Distinctive: line 141
Run the scout as Scout Before Review describes: the repository's own scout, before every source-changing review.
- Very specific: line 149
Tree: Run both scouts against a detached worktree at the exact head OID under review (git fetch origin pull/<PR>/head, then git worktree …
- Distinctive: line 154
Files: Keep task files and packs outside every worktree and outside the canonical state directory, and delete them with the PR worktree …
- Very specific: line 158
When a sweep fans review candidates out to subagents, the charter must carry these or the reports do not arrive:
- Distinctive: line 268
no unresolved blocking feedback.
- Distinctive: line 276
Before crediting a seam as correct, ask which existing authority already claims this rule, and whether the PR extended that one:
- Distinctive: line 301
Every review comment the loop posts — a single-mechanic review or a decomposed multi-mechanic pass — uses one structured, evidence-first …
- Very specific: line 320
When the user explicitly authorizes maintainer actions, the loop may pass clean PRs to pr-contribution-handler.
- Distinctive: line 326
When delegating a PR with a non-Frontier declaration, state explicitly that the declaration is an elevated-scrutiny signal, not a decline …
- Distinctive: line 328
Do not perform GitHub mutations from this skill except ordinary review/comment actions explicitly required by the current sweep and …
“Common” is measured: kept by at least 6 in 10 of the 16 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
PR Review Loop
Continuously review open contributor PRs, reprocessing only when GitHub state indicates new information: changed head, author follow-up, stale approval, stale request-changes, CI transition, queue drop, or a policy/hard-stop condition.
This skill is intentionally small. Mutable policy and contributor-specific state do not live here.
Sources Of Truth
- GitHub is authoritative for PR head, author, reviews, comments, labels, CI, and merge-queue state.
- Repo policy lives in
.agents/pr-review-policy.tomland must contain only repo-level, non-personal rules: path classifiers, domain capabilities, labels, hard-stop path patterns, generated-file patterns, and default gates. - Local review memory lives outside the repo by default under
~/.local/state/pr-review/<owner>__<repo>/unlessPR_REVIEW_STATE_DIRor--state-diris set. This directory contains:review-events.jsonl— the sole canonical store: an append-only local event log with locked, deduplicated,fsync'd appends.review-summary.json— generated token-minimal summary derived from the log.review-dashboard.json— generated dashboard snapshot. It is a derived cache, not review memory: it combines the current open-PR scan with a retained terminal-PR archive so closed-without-merge PRs remain visible after the 48-hour active window.github-discovery.json— disposable, versioned, repository-scoped raw GitHub discovery cache with the last successful query-start checkpoint.github-discovery.lockserializes the complete discovery/render/publish flow. Neither file is review memory or approval evidence; remove the cache or use--full-refreshto recover.- A stray
review-state.sqlitefrom an older build is an orphaned leftover; it is no longer read or written, and is safe to ignore or delete manually.
- Never Read
review-events.jsonldirectly. It is unbounded and not token-shaped; all queries must go through thepr_review.pyCLI (scan/inspect/recommend/analytics/compact).review-summary.jsonand the dashboard renderer'sreview-dashboard.jsoninput are the only state files intended for direct reading. - Repository writers bypass contributor-only gates. An author with write, maintain, or admin access (read live from GitHub's collaborator permissions, never from
authorAssociation, which also reports triage-only collaborators asCOLLABORATOR) is exempt from hard-stop path routing, architecture scope, frontend policy, and artifact admission;author_policy.repository_writermarks these packets. Their PRs still receive the full implementation review and the normal approval bar. Whenpr-contribution-handleris dispatched for one, pass the writer status so its path-based hard stops do not re-block the PR. - No hardcoded names. Contributor standings, frontend exceptions, reviewer identities, private overrides, and one-off maintainer policy belong in local/private state, never in this skill.
- Contributor standing lives in
private-overrides.jsonundercontributor_standing(skip/probation/watch/trusted, lowercase-matched logins). It sits in the gitignored state dir on the review host; other hosts see only derived standing. The narrative quality log is a historical appendix — the event log, via recordedsignals, is the data authority for per-contributor patterns. - Gittensor PR-history enrichment is advisory.
pr_review.pyfetches the public Gittensor PR feed by default and adds agittensorblock to packets when the author appears there. A high closed-PR count across other repos adds the genericgittensor-closed-heavyproof risk flag. Use it to increase caution and require concrete proof; do not cite it as a public accusation or reject a PR on that signal alone.
Commands
Use the CLI from the repo root:
python3 scripts/pr_review.py dashboard-data --repo phase-rs/phase --config .agents/pr-review-policy.toml
python3 scripts/pr_review.py dashboard-data --repo phase-rs/phase --full-refresh
python3 scripts/pr_review.py inspect <PR> --repo phase-rs/phase --mode full
python3 scripts/pr_review.py recommend <PR> --repo phase-rs/phase
python3 scripts/pr_review.py recommend <PR> --repo phase-rs/phase --emit-event
python3 scripts/pr_review.py record --event-json -
python3 scripts/pr_review.py observe <PR> --repo phase-rs/phase --summary "Looked at follow-up; no material action"
python3 scripts/pr_review.py compactdashboard-data is mandatory for every scheduled sweep; do not substitute scan. It atomically writes both the JSON snapshot and an adjacent review-dashboard.html (or the path supplied with --html-output) under the configured state directory. Its final JSON line reports output and html_output. Before reporting a sweep complete, verify that both reported files exist and are non-empty. pr_review_dashboard.py remains available to re-render an existing JSON file manually.
dashboard-data bootstraps a complete open inventory and bounded terminal history on its first run. Subsequent runs use paginated GitHub REST issue/comment queries with since set to the prior successful query start minus a short overlap. Ordinary issues are excluded; identical overlap payloads do not force another full detail fetch. A complete compact live open-PR census discovers new IDs and watches head, reviews and edits, comment metadata, routing labels, linked-issue approval metadata, CI, and queue/auto-merge transitions independently of the parent PR timestamp. Full PR detail is fetched only for new or changed metadata. The terminal archive is maintained from changes rather than rescanned each sweep. --limit must cover the entire open census; an incomplete census fails with an increase-limit message.
Every cached open PR still receives a fresh recommendation against current policy and local history. action_counts / candidates_by_action retain the complete inventory. sweep_candidates_by_action contains changed routing and unfinished actionable review/handler work; every unresolved review remains present on every sweep. Stable held, blocked, or deferred rows remain visible without repeated inspection after a suitable visible current-head maintainer disposition; a local event alone never completes a public disposition. Deferral completion requires the existing <!-- pr-review-deferred --> marker and exact current head. Hold completion requires an explicit held/hold response identifying the exact head, external condition, and next step; ambiguous comments remain work. Unpublished holds/deferrals remain work, and blocked rows remain work until a visible current-head formal requested-changes review exists; that formal disposition can finish the route even without local memory. Edited old comments are retained conservatively when recent GitHub history is incomplete. The compact census is a live safety read of all open PRs, so incremental discovery does not mean zero GitHub requests for unchanged PRs.
The checkpoint advances only after complete successful discovery, packet assembly, and both JSON and HTML writes. Multi-page REST results are replayed until membership stabilizes, within 20 requests per endpoint (40 per sweep, including replays). Budget exhaustion leaves the prior snapshot and checkpoint intact; an exhausted budget is an incomplete sweep. API pagination, partial GraphQL, truncation, or output failures leave the prior checkpoint intact for replay. --full-refresh rebuilds through the same publication flow; missing, corrupt, incompatible, or other-repository caches bootstrap automatically. scan remains a full live diagnostic and never advances the dashboard checkpoint. inspect and recommend always fetch live PR detail before an action; cache metadata never supplies approval.
record validates each event's event_type and (when present) outcome against a closed vocabulary and lowercases the outcome on write; an out-of-vocabulary event is rejected with exit 1 and the allowed values, and --force bypasses validation (flagging the event "forced": true). The preferred recording path is to add --emit-event to inspect/recommend, fill the returned event_skeleton (its prefilled timestamp gives idempotent retries), and pipe it back to record --event-json -.
Canonical-state ownership: run record only from the lead's repository checkout, which owns the configured canonical state directory. Review workers report their proposed event type, signals, summary, and current head to the lead; they must not record from a worktree or a private .agents/pr-review-state path. A local event is audit memory, never proof that GitHub received the disposition.
Import legacy state once:
python3 scripts/pr_review.py import \
--tracker /Users/matt/dev/forge.rs-pr-tracker.tsv \
--quality /Users/matt/dev/forge.rs-contributor-quality.md
python3 scripts/pr_review.py compactSweep Protocol
At sweep start, read .agents/pr-review/campaign-hotspots.toml if present (lead-maintained, untracked, updated at campaign routing/ship events). It lists: migrated areas with the rule now in force and the REDIRECT pointer for authors; coverage-delta semantics (an honest coverage DECREASE — silent swallows converted to explicit Effect::Unimplemented — is acceptable and must never be "restored"; in CI only the engine_regress bucket, a card LOSING a previously-supported handler, is fatal); diff content outside the contributor's control (generated-file dirt, export nondeterminism, staleness caused by maintainer-side churn — offer integration help without faulting the contributor or preventing their own rebase); and files owned by in-flight campaign units (a contributor PR racing those files → hold + surface to the maintainer). Hotspots inform routing and comment content; they are NOT an additional review gate — if a hotspot prohibition reaches review without CI redding it, that is a gate gap: file it, don't make the contributor absorb the miss.
- Resolve the acting identity from GitHub. Do not review PRs authored by the acting login.
Run
dashboard-datafor every scheduled sweep, instead ofscan. This is the required scan command: it writes the JSON triage packet and the adjacent static HTML page in one atomic flow. Capture its reportedoutput/html_outputpaths and verify both files are non-empty before continuing. A sweep whose dashboard generation fails is incomplete: report it as held with the command error rather than silently continuing withscan. Useaction_counts/candidates_by_actionto account for every open PR, andsweep_candidates_by_actionto dispatch changed, due, or unfinished work; do not infer legacy bucket names or hide a pending review. Stable held/blocked/deferred rows need another inspection when their metadata, routing, or deadline changes. Always live-inspect and rerunrecommendbefore acting. Treat the packet as triage, not a final approval gate. The page reloads itself every 60 seconds; no server or separate scheduler is needed.last GitHub checkis the snapshot generation time, whilelast recorded lookandlast material actioncome from local events. A material outcome inherently counts as a look; do not append a duplicateobservationfor it. Do not append anobservationmerely because the scanner ran; record one only after an actual human/agent look that has no material outcome.Public-disposition completion gate: local events and a zero
reviewcount are necessary but insufficient. For every PR inspected or reviewed this sweep, live-check GitHub before declaring it processed. A substantive blocker must have a current-head formalCHANGES_REQUESTEDreview, unless an existing current-head requested-changes review already states the same unresolved finding. A non-substantive hold must have a current-head maintainer comment explaining the exact external condition and next step. An approval/enqueue must be live-verified asAPPROVEDplus the expected queue/auto-merge state. Do not let a localblocked/heldevent substitute for a visible maintainer response.Explicit review-label override: the label configured as
labels.approved_for_reviewin.agents/pr-review-policy.tomlis a maintainer instruction to review the PR. Read the name from policy rather than repeating it here: the sweep must list the same labelrecommend_from_packetrecognises, or renaming it in policy silently stops labelled PRs from being forced into review. After generating the dashboard, live-list open PRs carrying it:LABEL=$(python3 -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('.agents/pr-review-policy.toml').read_text())['labels']['approved_for_review'])") gh pr list --repo <owner>/<repo> --state open --label "$LABEL" \ --json number,author,headRefOidFor every listed PR not authored by the acting login, treat the label as the highest-priority review-routing override: it supersedes
defer-fe, hard-stop routing, and every other advisory bucket, skip, standing, or default gate that would otherwise prevent a full maintainer review. Fetchinspect --mode fulland follow Current Review Skill Routing against the live head even when the dashboard classifies it as deferred orrequest_changes. Do not remove the label as part of review.The label grants review eligibility, not merge eligibility: it never bypasses a self-review exclusion, hard-stop safety handling, current-head evidence requirements, or the handler's approval/enqueue bar. A hard-stop finding discovered during the label-forced review still receives its normal visible blocker disposition. When recording that material disposition, set
review_routing_labelto the configured label name; the scanner uses that current-head marker to avoid repeatedly dispatching an unchanged labeled PR. Conversely, do not repeat a review solely because the label remains after a current-head formal disposition already addresses all findings; ordinary freshness triggers still govern re-review.- Every packet (and
recommendoutput) carries an advisorycontributorblock — standing, scrutiny,scrutiny_reasons,recurrence,first_contribution— derived from the local event log pluscontributor_standingoverrides; it isnullonly when the PR has no author login. Scale review depth by it:first_contribution→ full evidence bar, and point the author at thedocs/AI-CONTRIBUTOR.mdgates in the first review comment;elevated→ dig specifically into the recurring signals named inscrutiny_reasons;maintainer_attention→ include the contributor in the sweep report for the maintainer.light_touch_eligiblepermits a lighter pass only while scrutiny isnormal.
Model declarations route review depth; they do not authorize an automatic close. Frontier remains the requested contribution floor in docs/AI-CONTRIBUTOR.md, but a non-Frontier declaration or trailer is an elevated-scrutiny signal, never a decline by itself. Do not close a PR merely because its stated model falls below that floor.
For a non-Frontier PR, require the full evidence bar: accurate model declaration, concrete /engine-implementer (or a specific not-applicable) method record, current-head Gate A and final review-engine-impl evidence when applicable, relevant anchors, required verification, and a manual implementation review. A PR with that evidence must be reviewed on its merits. If the evidence is incomplete, request the missing proof or hold it; do not replace the review with a model-policy closure. An explicit maintainer message inviting continued review or asking the contributor to proceed also routes the current head to review, even if older prose describes a model-tier close.
A Co-authored-by: Cursor <cursoragent@cursor.com> trailer remains a scrutiny signal, not a closure reason. The behavioural CI-farming pattern — pushing unverified diagnostic commits or deleting passing assertions to obtain green CI — is review evidence on the current diff, not account-level or batch-close evidence. This maintainer-review rule intentionally overrides older automatic-close wording in docs/AI-CONTRIBUTOR.md for this workflow.
Check both surfaces, and read what actually matched before acting — a bare rg cursor hits WordCursor and other identifiers:
gh pr view <PR> --repo <owner>/<repo> --json body --jq .body | rg -i '^\s*\**Model:'
gh api repos/<owner>/<repo>/pulls/<PR>/commits --paginate \
--jq '.[] | "\(.commit.author.name) <\(.commit.author.email)> :: \(.commit.message)"' \
| rg -i 'cursoragent@cursor\.com|composer|haiku'The tell that distinguishes a tool-user from a CI-farmer is behavioural, not a trailer: reverting a fix to push a diagnostic commit so CI prints a value, or deleting a passing assertion to turn a job green. Those earn the standing change; the trailer alone does not.
4. Every packet carries separate artifacts, architecture_scope, and proof blocks. The gates have independent modes. Artifact verification remains audit-only until its immutable post-publication cutoff is activated; while it is in audit mode, report audit_would_decline and continue the existing review flow unchanged. The repository architecture-scope policy is review: a triggered, unauthorized cross-surface PR requires a full maintainer implementation review and must never be auto-closed merely for lacking an accepted issue. This includes bounded class work that turns a parser/engine Effect::Unimplemented path into supported behavior even when it needs existing choice, frontend, or transport plumbing. Reserve enforce for an explicitly configured future policy; only then does an unauthorized trigger decline before diff review. Neither audit result authorizes a comment, close, dequeue, or other mutation. Claimed parse impact remains optional manual quality evidence. proof.proof_gap remains the independent risk-evidence gate.
5. For each candidate:
hard_stop/request_changes— surface the precise blocker; do not enqueue. If the blocker follows this sweep's implementation review and no equivalent current-head formal requested-changes review exists, delegate topr-contribution-handlerto post one before recording the terminal outcome.decline— do not fetch or review the implementation diff. This route is valid only when the configured architecture mode is explicitlyenforce(or another independently enforced gate applies). Live-recheckstate,headRefOid, body, and auto-merge, rerunrecommend, and proceed only if the same current head still returnsdecline. Put the packet's completedecline_commentin a temp file, post it withgh pr comment <PR> --body-file <file>, then rungh pr close <PR>, record adeclineevent with the structured evidence, and stop. If auto-merge is enabled, disable it before commenting/closing. Audit-onlyaudit_would_declineis reporting data and authorizes no comment, close, dequeue, or mutation.skip— disambiguate byreason:closed/self_authoredneed no action;contributor_standing_skipis an explicit maintainer standing override meaning decline to review — record the skip and move on without reviewing. It does not authorize closing the PR. Checkskip_standing_policyinprivate-overrides.jsonfor the current configured action before assuming otherwise. A standing entry may carry analias_oflist of the same person's other accounts; that linkage is informational and carries no penalty of its own. A skip-listed contributor touching hard-stop paths still surfaces asrequest_changes(safety outranks the skip).
Closing is a judgement about a diff, never about an account. Two rules bound it, and both exist because they were once violated:
- Low-effort close (any author). An obviously low-effort PR is closed immediately regardless of the author's standing — a long merge history earns no pass, and a poor one earns no presumption. Close only on evidence visible in the PR itself: no substantive change, mechanical churn, an assertion duplicating coverage that already exists on the same code path, a test whose premise is fabricated (a named-card regression citing Oracle text the card does not have), or an
Effect::Unimplementedswallow dressed as a fix. Verify that evidence yourself before closing — re-read the cited file and check the claim againstcard-data.jsonor the CR text rather than trusting an earlier review's summary. A PR that is merely wrong, incomplete, or in need of another round is not low-effort; that is an ordinary changes-requested review. Prove the policy was in force before enforcing it. Before closing, declining, or acting against an account for a policy violation,
git logthe policy document and diff the version that was live at the PR'screatedAtagainst the rule you are applying. A rule that postdates the work cannot be violated by it. This is not hypothetical: on 2026-07-24 five PRs were closed and two contributors banned overclaude-haiku-4-5commit trailers, whenclaude-haiku-4-5was named in the accepted Standard row of the tier table live at the time and the Frontier-only rule landed hours after the newest affected PR was opened. Related: aCo-Authored-Bytrailer names the model that wrote a given commit, so read trailers against the commits carrying the implementation — a session that falls back mid-run leaves sub-floor trailers on a compliant change.A maintainer approval you posted yourself at a head that has not moved remains valid evidence. Do not discard it because the account later drew scrutiny; re-verify the head, then act on the approval. Behavioural concerns about how a change was produced are review findings on that change — raise them there, and do not let them become grounds for a batch action against unrelated PRs.
blocked— current head already has blocking maintainer feedback. Read the blocking feedback before deciding to wait. If GitHub has no current-head formal requested-changes review, do not infer one from a local event: re-review the current head and delegate a formalCHANGES_REQUESTEDreview throughpr-contribution-handlerwhen a substantive finding remains. If any part of the blocker is "the branch is stale / needs a rebase", first classify the cause per Maintainer-Caused Staleness below; when our own churn broke it, offer maintainer help without treating the drift as a contributor defect. This does not reserve the work exclusively for maintainers: the author may rebase, resolve conflicts and push for review without further permission. A formalCHANGES_REQUESTEDstate is not by itself a reason to keep waiting: if later maintainer feedback on the same head says the blocker is resolved, no unresolved finding remains, or the PR is otherwise clean-but-stuck because the formal review state was not cleared, delegate the PR topr-contribution-handlerin authorized mode to live-check, approve, label, and enqueue. If the only remaining blockers are maintainer-fixup sized, delegate the PR topr-contribution-handlerin authorized mode instead of making the contributor do another round-trip. Maintainer-fixup sized means small, local, low-risk corrections that do not change the accepted design or require new product/rules judgment: narrowing a claim in the PR title or body (gh pr edit --body-file), correcting the wording of a comment, doc comment or assertion message, replacing/removing an incorrect CR citation while preserving the already-reviewed logic, resolving a small merge conflict where the target logic already exists on one side, stripping accidental generated/noise hunks, fixing a single failing regression caused by main drift when the accepted design is unchanged, or threading an obviously missing renamed helper/import through the existing implementation. Do not use this path when there is any unresolved substantive behavior, architecture, proof-gap, test-discrimination, parse-diff, security, or hard-stop concern; keep the PR blocked until a new head or author follow-up. Author inactivity is never a reason to warn about or close a PR.defer— a defer is a visible, PR-specific maintainer routing outcome, never a silent bucket. Live-recheck the current head, then post the recommendation's completedefer_commentwithgh pr comment <PR> --body-file <file>before recording the event. It must identify the exact head, changed path class, policy reason, and explicitly say that the PR was triaged but not implementation-reviewed or approved. Use the<!-- pr-review-deferred -->marker and do not duplicate an existing marker for the same head. If the recommendation does not providedefer_comment, treat the sweep as incomplete (held); do not record a bare defer. Record the deferral event with the comment URL/ID anddefer_evidence, then do not approve, enqueue, or merge. If the recommendation carrieslabel_to_apply, add that label to the PR for maintainer filtering before moving on. Label names must come from repo policy, not from this skill.hold_ci— record a non-terminal hold only when the packet is incomplete or an external condition prevents review. CI being pending, unknown, or red is not itself a review/enqueue blocker; merge-when-ready will wait for required checks. When an implementation review was completed but CI is the only remaining condition, delegate a short current-head maintainer comment throughpr-contribution-handlerbefore recording the hold; state the pending check and that approval/enqueue will resume after it settles. Every subsequent sweep must recheck each current-head CI hold. A pending or unknown result remainshold_ci; once required CI is terminal (green or red), it must route asrecheck_ci_hold_for_handler, never fall through to a generichold. The handler live-checks the head and either approves/enqueues the clean green result or investigates the terminal-red result and records a concrete disposition.holdwith reasoninsufficient_admission_data— enforcement cannot prove whether the PR is legacy becausecreatedAtis missing or malformed. This is a maintainer/data blocker: do not inspect the implementation diff, comment, close, dequeue, or otherwise mutate the PR. Report the evidence and wait for corrected source data.queued— auto-merge is already enabled or the PR is already in the queue. Treat this as no action only while required checks are pending or green. If any required check is terminal red, the PR is not across the finish line: delegate topr-contribution-handlerin authorized mode to inspect the failing check, apply a maintainer-fixup-sized repair when appropriate, re-approve/re-enable auto-merge if a push disabled it, or report a real blocker. Do not leave approved-but-red PRs to sit merely because they were previously enqueued.dequeue_stale_for_handler/update_branch_for_handler/recheck_ci_hold_for_handler/approve_ready_for_handler— advisory only; delegate execution topr-contribution-handlerin authorized mode.recheck_ci_hold_for_handleris mandatory when a current-head CI hold reaches a terminal required-CI state; it is the completion gate that prevents a settled CI hold from becoming a silent generic hold.update_branch_for_handlerfires on bothBEHIND(auto-resolvable viagh pr update-branch) andCONFLICTING(a real conflict;update-branch422s). CheckmergeStateStatusfirst, and note that neither status detects semantic staleness — see Maintainer-Caused Staleness.review— fetch aninspect --mode fullpacket, then follow Current Review Skill Routing against the current head and GitHub API/local diff evidence. For engine/parser-surface PRs, the parse-diff sticky comment (<!-- coverage-parse-diff -->) is REQUIRED review evidence: fetch its full body and confront the card-level diff against the PR's claimed scope. The packet'sparse_difffield carries presence/state/updated_at. If state isbaseline_pendingon a stale branch (thereview_parse_baseline_pendingreason), route to update-branch first only when the PR history does not already contain a maintainer merge-main commit for the same baseline-pending churn. Repeated maintainer merge commits are PR spam: if the current head is otherwise clean and authorized mode would enqueue it after green CI, delegate topr-contribution-handlerto approve/enqueue now; if it is not clean, hold or review without mutating the branch. If the comment is absent but engine source changed, treat it as missing evidence: check whether CI ran for the current head before reviewing. If the review finds only a couple small, local, low-risk fixes between the PR and mergeability, do those maintainer fixups throughpr-contribution-handlerinstead of requesting another contributor round-trip; use the same maintainer-fixup boundary as theblockedroute above. If the manual quality gate passes, tell the handler to apply the existing policy-configuredqualitylabel with the type label; do not invent aquality_recommendedevent.
- After the public-disposition completion gate succeeds, the lead records every material outcome with
recordfrom the canonical checkout. Attachsignals(closed vocabulary, validated at record time) to the outcome event for observations from THIS review only, never re-recorded history. The vocabulary has two halves: defect signals (feed score penalties, windowed recurrence, and scrutiny) and praise signals (right-seam,scope-discipline,discriminating-runtime-test,parameterized-not-proliferated,evidence-backed-pushback— feed a capped score credit only, never recurrence or scrutiny). Never invent tokens: an out-of-vocabulary signal is rejected at record time, and if a needed concept is missing the fix is a vocabulary addition inpr_review.py, not a--force. Regenerate summaries withcompactwhen useful. The dashboard keeps an unmerged closure in its recent section for 48 hours, then moves it into its retained archive rather than deleting it; GitHub remains authoritative when a PR is reopened or later merged.
After any delegated approval/label/enqueue operation, independently run gh pr view <PR> --json labels and verify the expected type label and, when requested, quality label are actually present. Delegation success without the live labels is incomplete handling.
Use wrong-or-stale-cr-annotation for an incorrect, unrelated, or stale CR citation and duplicated-domain-vocabulary when a PR creates a second name/type/helper for an existing domain concept. If a recorded signal was factually wrong, append review_correction with corrects_event_id and only the mistaken signal subset; never compensate by adding praise.
Checkout Cleanup
Clean up temporary checkout directories as soon as their PR work is finished, including read-only review worktrees and completed handler fixup worktrees. Queue admission finishes local handling; do not keep a checkout merely to wait for the asynchronous merge.
- Track the exact path and creating agent for every temporary checkout. Include this cleanup requirement in every reviewer and
pr-contribution-handlerdelegation; each agent cleans up its own checkouts and reports removed or retained paths to the lead. - Before removal, confirm no agent, Tilt instance, or command still uses the directory. Check
git -C <path> status --porcelain --untracked-files=alland ensure any needed commits or artifacts remain recoverable outside that directory. A clean status alone does not establish that unpublished work is disposable. - Remove completed clean worktrees with
git worktree remove <path>from the owning repository, without--force. For a standalone temporary clone, remove only its exact owned directory after the same checks. Never use wildcard cleanup or delete the main checkout, another agent's directories, sharedtarget/, or canonical review state. - Retain unfinished work, dirty checkouts, and unpublished fixups still needed for verification or continuation. Report the exact retained path, reason, and next step; recheck that retention on the next sweep. Do not stash, reset, or discard changes to make cleanup succeed.
- Before reporting the sweep complete, confirm every checkout created for it was removed or explicitly retained with a reason. Report cleanup failures instead of silently accumulating directories.
Current Review Skill Routing
Before each new implementation-review dispatch, resolve the current installed implement-task skill from the skill catalog and read its file from disk, together with its bundled skills/review-implementation/SKILL.md rubric. Resolve the rubric relative to implement-task; it is an internal resource rather than a separate user-level skill. Use implement-task's reviewer/model rules under Shared gate rules for dispatch, including its current model/effort choices, native-agent/CLI fallbacks, and explicit user overrides. This imports review routing only; this PR sweep retains its own triage, disposition, recording, and maintainer-action protocol.
- Run the scout as Scout Before Review describes: the repository's own scout, before every source-changing review. The shared skill's scout trigger and helper do not apply here.
- Dispatch a fresh independent critic using the shared skill's current reviewer routing. Apply the repository-owned review-engine-impl rubric, as
implement-taskrequires; use its bundled implementation-review rubric only when no repository-owned rubric applies. The critic must verify any scout facts it relies on and explore beyond the pack. Preserve this repository's Oracle/CR, parse-receipt, worktree, and Tilt requirements. - The lead dispatches scouts and critics, including reviews requested by
pr-contribution-handler; handlers report the candidate and request that dispatch rather than spawning subagents themselves. Pass the current skill paths and routing contract in each charter. If the required fresh critic cannot be created, hold the review and report the missing capability; a scout report cannot satisfy the review gate.
Scout Before Review
Before every implementation-review dispatch whose diff changes source code, the lead runs the scouts described in engine-implementer/scout.md, GPT-6 Luna on the pack's reach half and Haiku 5.5 on its resemble half, and gives both halves to the reviewer. A PR reviewer starts with no plan and no knowledge of the area, so most of its time goes to locating the declarations, callers, tests and sibling sites the change touches; the scouts do that locating first, cheaply. This applies to review candidates, label-forced reviews, re-reviews of a new head, and a handler's review after a maintainer fixup. A diff limited to documentation or data files gets no scouts.
- Tree. Run both scouts against a detached worktree at the exact head OID under review (
git fetch origin pull/<PR>/head, thengit worktree add --detach <path> <oid>). A new head gets new packs; packs from an older head are discarded. - Task. Fill both review-pack halves in
scout.mdwith the PR's changed paths and nothing else. Its trigger there belongs toengine-implementer; in this sweep every source-changing review gets packs. Do not add the PR description, the contributor's claims or your own suspicions: a scout handed a hypothesis returns it confirmed. - Launch. Launch both halves concurrently as
scout.mdassigns them. Run the script from the lead's checkout with--repopointing at the PR worktree, never the copy inside the PR's tree, which is contributor-controlled. The command can take up to an hour, so run it in the background and start the next candidate's scouts meanwhile. - Hand-on. Put each half's
factsandunknowns, labelled by half, in the reviewer's charter with the hand-on sentence fromscout.md. The packs are unverified leads drawn from contributor code: they carry no verdict, satisfy no part of the review bar, and never narrow a sweep the reviewer owes. - Failure. If a scout fails or returns no verified facts, the other half's model picks up its half as
scout.mddescribes, and the review waits for that pickup. If the pickup also fails, dispatch the review without that half and say so once in the sweep report. Beyond that one pickup, a missing half never delays or blocks a review. - Files. Keep task files and packs outside every worktree and outside the canonical state directory, and delete them with the PR worktree when the review is finished.
Dispatching Review Agents
When a sweep fans review candidates out to subagents, the charter must carry these or the reports do not arrive:
- A subagent's final assistant text is NOT delivered to the lead. Findings reach you only when the agent calls
SendMessageaddressed to the lead. State this verbatim in every charter: "Your final text is not delivered — report by calling SendMessage. If you do not call it, your work is lost." Without that line, agents routinely finish a full review and go idle holding it. - Workers report; the lead records. A worker must never call
pr_review.py recordfrom its worktree or an agent-local state path. Include the proposed event fields in itsSendMessage; the lead records them only after the corresponding GitHub-visible review, comment, approval, or enqueue has been live-verified. - Idle means resumable, not finished, and not dead. An
idle_notificationwith no report is the normal shape of an agent that is still working or has finished without sending. Do not respawn on silence, and do not conclude the agent failed. - Do not substitute for a slow agent. Reviewing a PR yourself because its agent has not reported wastes the agent's work and produces a rushed review from a lead holding many PRs of context. Ping with an explicit "call SendMessage now" and wait. If you have already posted a substitute review when the agent's report lands, treat the report as a mandatory re-check of your own comment and post a correction for anything it overturns — do not quietly prefer your own version.
- Require the head OID in every report, and re-verify it against the live head before posting anything. A head that moved mid-review invalidates the findings; the contributor may have already fixed the blocker. This is the freshness invariant applied to review dispatch.
- Require file:line for every claim, and independently verify the load-bearing ones before posting. Agents produce confident, well-formatted, wrong findings. Verify at minimum: every CR citation, every claimed failing check, every "this is dead/unreachable" claim, and any finding you are about to call a blocker.
- An agent that corrects the lead's briefing is doing its job. Charter briefings carry the lead's own errors into the review. When an agent pushes back on a premise you supplied, verify its correction rather than defending the brief.
Re-reviews
A PR that already has a maintainer review gets one consolidated re-review. Give the reviewer the earlier maintainer reviews and, next to the full diff, the diff from the last reviewed head to the current head (git diff <reviewed_head> <head> in the PR worktree; git range-diff when the branch was rebased), and, for the round limit, the number of earlier maintainer reviews that requested changes, including any now DISMISSED. review-engine-impl PR Review Mode states how the reviewer carries earlier findings forward and what counts as a late finding.
Before posting. Close every maintainer-fixup-sized finding yourself before posting: edit the PR body, or push a fixup commit to the contributor's branch. List each one under 🟡 as done by the maintainer. A review never asks a contributor for a text-only change; when nothing else blocks, approve. A fixup commit moves the head: confirm the new head is the reviewed head plus only that commit, then post on the new head. Check each new finding's anchor against that diff. A new finding on code the author has not changed since the last reviewed head is late: it is posted as a numbered finding only when the reviewer named a must-fix category for it, and otherwise goes under 🟡 as a Late note: line, which is never an issue or a deferral. A late finding without a must-fix category goes back to the reviewer before posting; never demote one on your own judgement. A finding of wrong card or rules behaviour whose evidence names no printed-card witness in a legal game goes back to the reviewer for its Reach verdict. A finding an earlier review left open appears once, marked (carried from <URL>).
CodeRabbit. Post each refuted CodeRabbit item as one line under 🟡.
Maintainer-side code. Findings on maintainer-side commits (keep-both resolutions, fixups) are the handler's to fix.
Verifying the Review's Own Evidence
The evidence bar in this skill binds the reviewer exactly as it binds the contributor. A review comment is a published artifact with the maintainer's authority behind it; a wrong citation in it is worse than a wrong citation in a PR, because the contributor will act on it.
- Grep-verify every CR number the review itself cites, not only the ones the PR cites, and quote the rule text rather than paraphrasing it. Never cite from memory. This applies with full force to a CR number you are using to tell a contributor that their CR number is wrong.
- Prefer the dedicated rule over an adjacent general one, and check repo convention first. Before proposing a citation, grep the codebase for how this rule is already cited (
rg "CR 115\.3" crates/). If the repo standardises a pairing at many sites, match it. Proposing a different-but-defensible rule than the twenty existing sites use creates exactly the drift the annotation rule exists to prevent. - Confirm the rule says what the claim needs. A rule number that exists, in roughly the right section, is not verification — read it. Adjacent subrules in the same section routinely cover unrelated single cards (CR 612.5 is Exchange of Words; CR 612.6 is Volrath's Shapeshifter), and layer placement often lives in a different section entirely from the effect it orders (CR 613.1c, not CR 612.x).
- When a correction is warranted, post it plainly to the same PR and record a corrected event. State what was wrong and what is right, do not re-litigate, and make clear which parts of the earlier comment still stand so the contributor knows what to act on.
Review Freshness
Approval freshness is attached to a head, not to a PR number. A post-approval force-push, same-head newer blocking maintainer activity, author follow-up after review, or queue drop must re-surface the PR. A terminal local event never overrides newer GitHub activity.
The CLI models freshness using:
- current
headRefOid; - latest maintainer comment/review and the commit SHA attached to formal reviews;
- author follow-ups;
- substantive vs merge-only commits;
- review decision;
- CI status as evidence only, not as a pre-review or merge-when-ready gate;
- labels and merge-queue membership.
Redundant-review guard. The converse of the freshness invariant: when the most recent comment or review on the PR was authored by a repository member (GitHub authorAssociation of OWNER, MEMBER, or COLLABORATOR — including the acting login), the ball is in the contributor's court and there is no unacknowledged follow-up to respond to. Do not dispatch a redundant review of the same head. This guard suppresses only redundancy: it never overrides the mandatory re-review triggers below (changed head, queue drop, stale approval, edited author activity), which act on state, not on who spoke last.
Freshness invariant. Before accepting held, blocked, queued, or a previously approved no-action result, the sweep must compare the current headRefOid with the most recent locally recorded head. A different head is a mandatory re-review candidate (or update_branch_for_handler when it conflicts), never an inherited hold. Likewise, an author comment/review created or edited after the latest GitHub-visible maintainer comment/review is an unacknowledged follow-up even if a later local event recorded a hold. Local event timestamps are observations, not contributor responses. If the scanner cannot prove that it has the relevant recent comment history, it must surface the PR for review rather than preserve the state. Explicit capability-policy deferrals and self/standing skips remain policy decisions, not inherited review states.
Stale approval plus armed auto-merge is a safety defect, not bookkeeping. When dismiss-stale-reviews is not enabled on the repo, GitHub keeps reporting reviewDecision: APPROVED after a new commit lands, so an unreviewed head can sit armed to merge with nothing surfacing it — the scanner's head_changed_since_local_event is the only signal. Treat this as a priority case, not a formality: compare the approving review's commit.oid against the live headRefOid, and when they differ, review the delta before anything merges. Resolve it by making the record honest — review the new commit and re-approve on the current head, or disarm auto-merge — never by leaving the stale approval to carry.
This applies with more force when the post-approval commit is maintainer-authored (a fixup pushed onto the contributor's branch). Maintainer commits are the least likely to receive a second look and frequently carry rules-correctness changes and cross-file renames. Verify a maintainer fixup to the same standard as contributor code — grep-verify its CR claims, confirm rename censuses via the compiler rather than rg, and check that any newly exercised code path has a test — before re-approving on it.
Maintainer-Caused Staleness
Before blocking a PR on "needs rebase", classify why it went stale so feedback assigns fault accurately and offers useful help. Contributors may always rebase, resolve conflicts and push their own PR for fresh review. Maintainer help is an offer, not an exclusive reservation or a prerequisite for contributor progress.
Only a confirmed active edit of the same branch warrants a short coordination pause: name the owner and concrete work, arrange a handoff, and release it when editing stops. An old comment, an unassigned PR, unknown private-worker activity or an unrecovered unpublished candidate does not establish active ownership and must never indefinitely prevent the author from continuing. Preserve any recoverable maintainer work separately; do not make its recovery a gate on the author. When earlier feedback told an author to stand down on that basis, explicitly correct it in the PR.
- Maintainer-caused — main's own refactor churn invalidated the branch, or a PR merged during the review window rewrote the same seam. Signature: the branch was fine when it was opened or last reviewed, and it broke without the author touching it. Offer the replacement authority and maintainer integration help, especially for small mechanical ports. The contributor may also do the integration, and an author volunteering to rebase should be encouraged to proceed. Larger ports can be coordinated explicitly; do not promise an unbounded maintainer rescue or require the author to await one.
- Contributor-caused — fork hygiene (unrelated history, an orphan or force-pushed branch, no merge-base), or the author's own change colliding with long-settled main code. Bounce it, unless it is mechanically cheap to fix, in which case just fix it.
A PR can be stale for both reasons at once, and can also carry substantive blockers of its own. Rebasing it does not clear those — resolve the staleness, then re-review the delta on the new head.
A compile error is not proof of contributor fault — check ancestry first. E0004 non-exhaustive-match failures from a PR's own new enum variants look exactly like contributor sloppiness ("you added a variant and missed the match arms") and are the easiest misattribution in the whole loop. They are frequently ours: main adds a new match site over an existing enum after the branch was written, and a PR that was complete when authored is now missing an arm in a file it never touched.
The question to answer is not "which is newer" but "did the branch ever contain the failing code?" Ask it by ancestry, never by timestamp — commit dates are author/committer metadata, not push time, so a rebase, an amend, or a long-delayed push all skew a date comparison, and a squash-merged main commit carries a date unrelated to when its content landed:
# 1. Did the failing file even exist at the PR head? Often the whole answer.
# Use ls-tree, NOT `cat-file -e <sha>:<path>` — see the warning below.
[ -n "$(git ls-tree <headOid> <file-with-the-error>)" ] \
&& echo "file present at head" \
|| echo "file absent at head — the branch never had it"
# 2. Which commit introduced the match site, and is it in the branch's history?
site=$(git log -S '<missing-symbol>' --format=%H -1 -- <file-with-the-error>)
git merge-base --is-ancestor "$site" <headOid> \
&& echo "in the branch's history — the author could have covered it" \
|| echo "NOT in the branch's history — maintainer-caused"
# 3. Is the file in the PR's own diff at all?
gh api repos/<owner>/<repo>/pulls/<PR>/files --paginate --jq '[.[].filename]'Do not use git cat-file -e "$sha:<path>" for step 1. In this environment the <rev>:<path> form is corrupted before git sees it: the : plus the path's first character is swallowed, so "$head:crates/…" reaches git as <sha>rates/… and dies with fatal: Not a valid object name. Quoting does not help — the rewrite happens above the shell (set RTK_DISABLED=1 and it stops). Paired with the 2>/dev/null || echo "file absent" idiom this fails silently and in the maintainer-blaming direction: every path beginning with a letter git's rev-parse treats as a modifier reports "the branch never had it", which reads as proof of maintainer-caused staleness for a file the branch does have. git ls-tree <sha> <path> takes the rev and path as separate arguments and is unaffected. Verified 2026-07-24 on real PR heads where cat-file claimed absent and ls-tree showed the blob.
If the failing site is not an ancestor of the head, or the file is absent from the head or from the PR's own file list, the contributor could not have covered it: this is maintainer-caused staleness. Explain the changed authority and offer help; do not penalize the contributor for it. They remain free to rebase or port it themselves, including coordinated protocol assertions, and submit the resulting head for fresh review.
Sanity-check the probe before trusting a clean result: a commit you know is in the branch's history (git merge-base origin/main <headOid>) must report ancestor. A check that returns "not an ancestor" for everything is broken, not exonerating. Timestamps remain useful as human-readable colour in the review comment — label them "committed at", never "pushed at" — but they must not be the test.
The same procedure applies to a whole board of red jobs sharing one root cause: diagnose the single cause before attributing eight failures to the author.
Textual vs semantic staleness. mergeStateStatus is a textual check and is not evidence the branch is healthy:
- Textual (
DIRTY/CONFLICTING) — announces itself. Cheapest case. - Semantic (
BEHIND, or evenMERGEABLE) — git merges it without a single conflict and it still does not compile, or worse, compiles and silently drops behavior. This is strictly nastier thanDIRTYprecisely because nothing flags it. AMERGEABLEbranch sitting under a refactor that deleted a type it depends on will report clean right up until the build fails.
Never resolve a semantic conflict by picking a side. Where both sides changed the same seam, name the behavior each side contributes, then require a discriminating test from each side green on the rebased head before approving. Taking --ours or --theirs on a seam both PRs deliberately modified silently drops one of them, and by construction neither PR's own tests will catch it.
Mechanics. Push to the contributor's branch only when maintainerCanModify is true. Rebase their commits preserving %an/%ae, and put the port or conflict resolution in a separate follow-up commit trailing Co-authored-by: the contributor — their work stays theirs, and the diff shows exactly what we changed and why. Re-verify locally before pushing; do not push a port that only compiles.
Review Bar
The bar is still owned by review-engine-impl and pr-contribution-handler:
- correct architectural seam;
- idiomatic implementation at that seam;
- maintainability and building-block reuse;
- value proportional to blast radius;
- discriminating tests that would fail on revert;
- rules/CR evidence when the repo policy enables the MTG Comprehensive Rules domain;
- no unresolved blocking feedback.
The CLI may recommend that a PR is ready for handler execution only when its structured gates say so, but the recommendation is advisory. Queue readiness is never satisfied from cache; the executor must live-check GitHub.
Judging the seam
"Reuses existing machinery" is not the same as "correct seam." A PR that adds no enum variant, no bool, and no new enforcement code reads as architecturally clean and will pass a quick review — but reusing the wrong existing mechanism is still a wrong-seam defect, and it is harder to spot precisely because every proliferation heuristic says yes.
Before crediting a seam as correct, ask which existing authority already claims this rule, and whether the PR extended that one:
- Grep for the rule, not the symbol: apply it as
review-engine-impl's seam lens (Universal Lens 1) states it. - Check whether the existing authority is one type-parameter short. The common shape is an authority that implements half a rule (
HashSet<ObjectId>where the rule says "object or player") and silently drops the other half via a_ => None. Widening it fixes the whole class at once; bolting on a parallel mechanism entrenches the split. - Two mechanisms for one rule is the defect. If after the PR one half of a rule is enforced on one path set and the other half on a different path set, that is wrong-seam regardless of how little code was added. Trace both the selection path and the validation path before concluding a fix is complete.
- Look for the repo asking for the primitive. Strict-fail comments,
EnginePrerequisiteMissinggaps, andneeded_variantmarkers are the codebase naming the general primitive it is waiting for. A PR that special-cases around such a marker instead of satisfying it is adding call sites to unwind later; cite the marker in the review. - Weigh serialized-versus-live reach. A fix written into a serialized field (
card-data.json) is inert until data regen and only reaches abilities built by that one producer; the equivalent fix in the runtime authority is live immediately and covers every producer. Prefer the runtime authority when both are available.
Test-only and regression-test PRs
A PR that adds only tests — no engine, parser, or frontend behavior change — must clear a high value bar before it is worth merging. The suite already carries extensive coverage, so a new test earns its place only when it meaningfully reduces risk that existing tests do not already cover. A test-only PR is not "safe because it only adds tests"; a redundant or non-discriminating test is net-negative — it slows the suite, dilutes intent, and adds maintenance cost for no signal.
Start from skepticism about standalone test PRs. In this repo, bug fixes almost always ship their own regression test in the same PR that fixes the bug. So a separate, later PR adding another test for an already-fixed issue is usually redundant by construction — the fixing PR already covered it. Before evaluating the test itself, find the PR that fixed the linked issue and check whether it already added a regression test (gh pr list --search "<issue#> in:body", or read the closing commit); if coverage already exists, the new test is duplicative and does not clear the bar — record value-bar citing the existing test. A standalone test-only PR only makes sense when the coverage genuinely does not already exist: a bug fixed long ago with no test, or a still-uncovered edge of a mechanic. Conversely, if the linked issue is still open (the bug is unfixed), a test asserting the fixed behavior is premature — it will fail against current main; that is a block until the fix lands, not a merge. Weigh:
- Does it guard a real, non-obvious regression? A test pinning a defect that was actually fixed (a linked issue with a genuine bug) clears the bar. A test restating behavior that existing tests already exercise does not.
- Is it discriminating? It must fail on the pre-fix code or against a plausible wrong implementation. A test that passes regardless of the behavior it claims to cover is worthless. Verify the
modregistration intests/integration/main.rsfor integration tests — an unregistered test compiles to nothing and shows green (inert false-green). - Is the coverage unique? Grep for existing tests over the same card, mechanic, or issue before accepting. Duplicated coverage of an already-tested path is a reason to decline, not merge.
- Is the blast radius justified? Large test files that re-link the engine (see the
no_top_level_test_binariesguard) must earn their compile cost.
Evaluate every test-only PR independently. A series of narrowly scoped test PRs earns no collective presumption of value: each PR must cite the specific existing coverage it does not duplicate, name the distinct regression it guards, and demonstrate a failure against the plausible pre-fix or wrong implementation. “This is another test for the same area” is not merge value.
Default to the value-bar signal — with a concrete "what already covers this" citation — when a test-only PR does not clear this bar, and do not enqueue it on green CI alone. Approve only when the added coverage is genuinely load-bearing. Apply the same discriminating-test standard whether tests ship alone or alongside a fix.
Review Comment Format
Every review comment the loop posts — a single-mechanic review or a decomposed multi-mechanic pass — uses one structured, evidence-first format. Lead with the verdict, group findings by severity, anchor every finding to file:line, and cite evidence inline rather than paraphrasing it.
Structure:
- One-line verdict in bold — the decision and its shape (e.g. "7 of 8 mechanics clean; 1 blocked on a rules defect — recommend splitting the blocked mechanic so the rest land now.").
Findings grouped by severity, most severe first, under clear headers:
## 🔴 Blocker— anything that must change before merge. State the defect, anchor it tofile:line, and give the evidence: for a card-behavior blocker, the printed card, its verbatim Oracle text and the grep-verified CR number (real cards), plus any official ruling it needs (quoted, never paraphrased — a paraphrase is exactly how a fabricated clause survives review). Then point to the fix: name the existing building block to reuse or the general pattern to adopt, not just "this is wrong."## 🟡 Non-blocking— late notes, reach notes, Pre-existing entries and refuted external items, one line each; say why each does not block. An introduced finding never goes here.## ✅ Clean(or a praise section) — credit what is right, specifically (verified Oracle text, grep-verified CR annotations, discriminating registered tests). Contributors calibrate on what passed as much as on what failed.
Under 🔴, each finding starts a new paragraph whose first line begins
**F<n> · <SEV> —, with<SEV>one of CRITICAL, HIGH, MED, LOW or NIT and<n>counting from 1 in each review. Inside a finding, a paragraph or list item may begin with bold only as a label: one to four words, then a colon, written**Label:**or**Label: …**, where the first word is not a severity word. Every other paragraph or list item starts with plain text. The lead posts the reviewer'sF<n>heads unchanged under 🔴 and runs nothing that renumbers them; a head that does not match this grammar is corrected by the lead before posting. The 🔴 section contains only the reviewer's numbered findings, with the F1 head directly after the header. The reviewed-head line and any verdict or summary line go above the first##header. Use no#headings inside 🔴. ListLate note:andReach note:lines, Pre-existing entries and refuted external items under 🟡, unnumbered.- A concrete recommendation in bold — the actionable next step:
request-changeswith the exact fix,splitthe blocked mechanic (and what to keep on the landing side),approve on settled green, and so on. A review that requests changes ends with this line, so the author's agent fixes the batch in one push:To address this review in one push, follow https://github.com/phase-rs/phase/blob/main/.claude/skills/address-review/SKILL.md.
Reference example: PR #5534 review.
Keep the tone specific and grounded: credit correct work, cite evidence for every claim, and avoid contrastive "not X, but Y" filler. The goal is an auditable decision — a maintainer skimming the comment should see the blocker, its evidence, and the fix without opening the diff.
Authorized Mode
When the user explicitly authorizes maintainer actions, the loop may pass clean PRs to pr-contribution-handler. That skill owns assignee locks, checkout/worktree handling, fixups, formal approval, labels, update-branch, enqueue, dequeue, and live GraphQL verification.
Include Current Review Skill Routing in the handler charter for any fresh implementation review, including a maintainer fixup at a new head.
When delegating labeling, require the handler to classify by the actual diff: ordinary additive engine, parser, or tooling capabilities are enhancement by default, even when they touch several files. Reserve feature for a genuinely broad mechanic or product change spanning distinct subsystems (for example, a combo workflow that jointly changes engine rules, priority handling, UI, and AI). Never infer feature from a feat: title, file count, or author identity.
When delegating a PR with a non-Frontier declaration, state explicitly that the declaration is an elevated-scrutiny signal, not a decline authorization. The handler must review the current head against the evidence bar above and may only close for a diff-based or independently enforced reason.
Do not perform GitHub mutations from this skill except ordinary review/comment actions explicitly required by the current sweep and policy-configured deferral labels. Approval, queue, update-branch, dequeue, and merge execution still belongs to pr-contribution-handler.
Drift Rule
.agents/skills is a symlink to .claude/skills, so .claude/skills/pr-review-loop/SKILL.md is the single physical copy for both Claude Code and Codex. Do not create a separate file under .agents/; if the symlink is ever replaced with a real directory, restore it rather than maintaining two copies.
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.

