agentleFS
phase-rsphase-rs/phase/.claude/skills/pr-review-loop/SKILL.md

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

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
  1. Distinctive:

    Use the CLI from the repo root:

    line 30
  2. Distinctive:

    Import legacy state once:

    line 55
  3. Very specific:

    Check both surfaces, and read what actually matched before acting — a bare rg cursor hits WordCursor and other identifiers:

    line 92
  4. Very specific:

    After any delegated approval/label/enqueue operation, independently run gh pr view <PR> --json labels and verify the expected type label …

    line 123
  5. Very specific:

    Before removal, confirm no agent, Tilt instance, or command still uses the directory.

    line 132
  6. Distinctive:

    Before reporting the sweep complete, confirm every checkout created for it was removed or explicitly retained with a reason.

    line 135
  7. Distinctive:

    Run the scout as Scout Before Review describes: the repository's own scout, before every source-changing review.

    line 141
  8. Very specific:

    Tree: Run both scouts against a detached worktree at the exact head OID under review (git fetch origin pull/<PR>/head, then git worktree …

    line 149
  9. Distinctive:

    Files: Keep task files and packs outside every worktree and outside the canonical state directory, and delete them with the PR worktree …

    line 154
  10. Very specific:

    When a sweep fans review candidates out to subagents, the charter must carry these or the reports do not arrive:

    line 158
  11. Distinctive:

    no unresolved blocking feedback.

    line 268
  12. Distinctive:

    Before crediting a seam as correct, ask which existing authority already claims this rule, and whether the PR extended that one:

    line 276
  13. Distinctive:

    Every review comment the loop posts — a single-mechanic review or a decomposed multi-mechanic pass — uses one structured, evidence-first …

    line 301
  14. Very specific:

    When the user explicitly authorizes maintainer actions, the loop may pass clean PRs to pr-contribution-handler.

    line 320
  15. Distinctive:

    When delegating a PR with a non-Frontier declaration, state explicitly that the declaration is an elevated-scrutiny signal, not a decline …

    line 326
  16. Distinctive:

    Do not perform GitHub mutations from this skill except ordinary review/comment actions explicitly required by the current sweep and …

    line 328

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.toml and 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>/ unless PR_REVIEW_STATE_DIR or --state-dir is 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.lock serializes the complete discovery/render/publish flow. Neither file is review memory or approval evidence; remove the cache or use --full-refresh to recover.
    • A stray review-state.sqlite from 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.jsonl directly. It is unbounded and not token-shaped; all queries must go through the pr_review.py CLI (scan/inspect/recommend/analytics/compact). review-summary.json and the dashboard renderer's review-dashboard.json input 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 as COLLABORATOR) is exempt from hard-stop path routing, architecture scope, frontend policy, and artifact admission; author_policy.repository_writer marks these packets. Their PRs still receive the full implementation review and the normal approval bar. When pr-contribution-handler is 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.json under contributor_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 recorded signals, is the data authority for per-contributor patterns.
  • Gittensor PR-history enrichment is advisory. pr_review.py fetches the public Gittensor PR feed by default and adds a gittensor block to packets when the author appears there. A high closed-PR count across other repos adds the generic gittensor-closed-heavy proof 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 compact

dashboard-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 compact

Sweep 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.

  1. Resolve the acting identity from GitHub. Do not review PRs authored by the acting login.
  2. Run dashboard-data for every scheduled sweep, instead of scan. This is the required scan command: it writes the JSON triage packet and the adjacent static HTML page in one atomic flow. Capture its reported output / html_output paths 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 with scan. Use action_counts / candidates_by_action to account for every open PR, and sweep_candidates_by_action to 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 rerun recommend before 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 check is the snapshot generation time, while last recorded look and last material action come from local events. A material outcome inherently counts as a look; do not append a duplicate observation for it. Do not append an observation merely 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 review count 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 formal CHANGES_REQUESTED review, 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 as APPROVED plus the expected queue/auto-merge state. Do not let a local blocked/held event substitute for a visible maintainer response.

    Explicit review-label override: the label configured as labels.approved_for_review in .agents/pr-review-policy.toml is a maintainer instruction to review the PR. Read the name from policy rather than repeating it here: the sweep must list the same label recommend_from_packet recognises, 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,headRefOid

    For 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. Fetch inspect --mode full and follow Current Review Skill Routing against the live head even when the dashboard classifies it as deferred or request_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_label to 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.

  3. Every packet (and recommend output) carries an advisory contributor block — standing, scrutiny, scrutiny_reasons, recurrence, first_contribution — derived from the local event log plus contributor_standing overrides; it is null only when the PR has no author login. Scale review depth by it: first_contribution → full evidence bar, and point the author at the docs/AI-CONTRIBUTOR.md gates in the first review comment; elevated → dig specifically into the recurring signals named in scrutiny_reasons; maintainer_attention → include the contributor in the sweep report for the maintainer. light_touch_eligible permits a lighter pass only while scrutiny is normal.

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 to pr-contribution-handler to 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 explicitly enforce (or another independently enforced gate applies). Live-recheck state, headRefOid, body, and auto-merge, rerun recommend, and proceed only if the same current head still returns decline. Put the packet's complete decline_comment in a temp file, post it with gh pr comment <PR> --body-file <file>, then run gh pr close <PR>, record a decline event with the structured evidence, and stop. If auto-merge is enabled, disable it before commenting/closing. Audit-only audit_would_decline is reporting data and authorizes no comment, close, dequeue, or mutation.
  • skip — disambiguate by reason: closed / self_authored need no action; contributor_standing_skip is an explicit maintainer standing override meaning decline to review — record the skip and move on without reviewing. It does not authorize closing the PR. Check skip_standing_policy in private-overrides.json for the current configured action before assuming otherwise. A standing entry may carry an alias_of list 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 as request_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::Unimplemented swallow dressed as a fix. Verify that evidence yourself before closing — re-read the cited file and check the claim against card-data.json or 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 log the policy document and diff the version that was live at the PR's createdAt against 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 over claude-haiku-4-5 commit trailers, when claude-haiku-4-5 was 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: a Co-Authored-By trailer 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 formal CHANGES_REQUESTED review through pr-contribution-handler when 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 formal CHANGES_REQUESTED state 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 to pr-contribution-handler in authorized mode to live-check, approve, label, and enqueue. If the only remaining blockers are maintainer-fixup sized, delegate the PR to pr-contribution-handler in 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 complete defer_comment with gh 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 provide defer_comment, treat the sweep as incomplete (held); do not record a bare defer. Record the deferral event with the comment URL/ID and defer_evidence, then do not approve, enqueue, or merge. If the recommendation carries label_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 through pr-contribution-handler before 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 remains hold_ci; once required CI is terminal (green or red), it must route as recheck_ci_hold_for_handler, never fall through to a generic hold. 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.
    • hold with reason insufficient_admission_data — enforcement cannot prove whether the PR is legacy because createdAt is 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 to pr-contribution-handler in 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 to pr-contribution-handler in authorized mode. recheck_ci_hold_for_handler is 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_handler fires on both BEHIND (auto-resolvable via gh pr update-branch) and CONFLICTING (a real conflict; update-branch 422s). Check mergeStateStatus first, and note that neither status detects semantic staleness — see Maintainer-Caused Staleness.
    • review — fetch an inspect --mode full packet, 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's parse_diff field carries presence/state/updated_at. If state is baseline_pending on a stale branch (the review_parse_baseline_pending reason), 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 to pr-contribution-handler to 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 through pr-contribution-handler instead of requesting another contributor round-trip; use the same maintainer-fixup boundary as the blocked route above. If the manual quality gate passes, tell the handler to apply the existing policy-configured quality label with the type label; do not invent a quality_recommended event.
  1. After the public-disposition completion gate succeeds, the lead records every material outcome with record from the canonical checkout. Attach signals (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 in pr_review.py, not a --force. Regenerate summaries with compact when 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-handler delegation; 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=all and 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, shared target/, 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-task requires; 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, then git 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.md with the PR's changed paths and nothing else. Its trigger there belongs to engine-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.md assigns them. Run the script from the lead's checkout with --repo pointing 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 facts and unknowns, labelled by half, in the reviewer's charter with the hand-on sentence from scout.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.md describes, 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 SendMessage addressed 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 record from its worktree or an agent-local state path. Include the proposed event fields in its SendMessage; 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_notification with 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 even MERGEABLE) — git merges it without a single conflict and it still does not compile, or worse, compiles and silently drops behavior. This is strictly nastier than DIRTY precisely because nothing flags it. A MERGEABLE branch 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, EnginePrerequisiteMissing gaps, and needed_variant markers 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 mod registration in tests/integration/main.rs for 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_binaries guard) 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:

  1. 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.").
  2. Findings grouped by severity, most severe first, under clear headers:

    • ## 🔴 Blocker — anything that must change before merge. State the defect, anchor it to file: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's F<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 🔴. List Late note: and Reach note: lines, Pre-existing entries and refuted external items under 🟡, unnumbered.

  3. A concrete recommendation in bold — the actionable next step: request-changes with the exact fix, split the 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.