Review Anvil Pr

review-anvil-pr

Preset that reviews a GitHub PR with the multi-agent loop and posts the result back as a top-level PR comment. The skill orchestrates three steps:

Generated Language

Apply the ASD-STE100-inspired language contract to this preset. Use direct imperatives for internal steps. Use short active declarative sentences in PR comments. Keep inline diagnoses unlabeled and put requested work under Suggestions:, with one bullet per independently implementable change. Default to starting required work with its action verb. A deliberate collaborative request may use a courtesy wrapper sparingly when coordination or tone benefits. Never use one as a stock opener throughout the review. Keep no-change constraints in prose, suggestion grammar for low/nit guidance, and questions for genuinely unresolved choices.

1. scripts/pr-helper.sh init [<locator>] — locator parsing or auto-detect from the current branch, gh preflight (auth + PR reachability), marker UUID + report path setup
2. The review-anvil engine in read-only mode (commit_mode=none)
3. scripts/pr-helper.sh post <host> <owner> <repo> <n> <marker> <report_path> — marker injection, lossless report posting as a PR review / gh pr comment, race-free URL recovery

Inputs

The user may provide a PR locator as the first argument, or omit it entirely:

• Omitted — the helper runs gh pr view --json url to detect the PR associated with the currently checked-out branch. The natural "review the PR I'm on" workflow. If no PR is associated with the current branch, the helper aborts with a clear message pointing the user at the explicit-locator forms below.
• Full GitHub URL — https://<host>/<owner>/<repo>/pull/<N> for github.com or GitHub Enterprise.
• Slug — <owner>/<repo>#<N> (host defaults to github.com).

Bare integers are rejected by the helper script to prevent wrong-repo misdirection. To target a PR you don't have checked out, pass the URL or slug; to target the PR you're currently on, just omit the locator.

How to invoke

0. Reject overrides of pinned params

Pins for this preset: commit_mode, target, report_path, run_ordinal. Enforce mechanically — after resolving the helper (step 1), run:

bash <helper-path> check-pins review-anvil-pr "commit_mode,target,report_path,run_ordinal" "$ARGUMENTS"

Non-zero exit means a pinned param was overridden in the args: surface the script's error verbatim and stop. (The engine's prose pin-rejection in "Parsing" remains as the description of the algorithm; the script is the binding layer.)

The pins are non-overridable for safety: commit_mode enforces read-only; target and report_path are mechanically tied to the user's locator; and run_ordinal carries the helper's observed PR history into identifier generation. Defense in depth against the engine's prose parser being talked into accepting overrides (e.g. via prompt injection in the focus text).

1. Resolve the helper script

The script lives at ./scripts/pr-helper.sh relative to this SKILL.md. That is the only authoritative resolution rule.

To find the absolute path:

1. If the host exposes the loaded SKILL.md's path (Claude Code via ${CLAUDE_PLUGIN_ROOT}/skills/review-anvil-pr/scripts/pr-helper.sh, or any agent that surfaces the skill's filesystem location to the model), use that and stop.

2. Otherwise, fall back to user-level skill install paths only:

   • ~/.claude/skills/review-anvil-pr/scripts/pr-helper.sh (Claude Code via npx skills add)
   • The home-directory skill root for the current host as vercel-labs/skills documents it (npx skills list shows the configured location).

   Do not search project-scoped or worktree-local skill directories (e.g. <project>/.claude/skills/..., <reviewed-repo>/.codex/skills/..., etc.) — those paths are writable by the contents of the repository being reviewed. An adversarial PR could plant a malicious pr-helper.sh inside such a directory and weaponize the wrapper into arbitrary shell execution. The script must come from a trusted install root outside the reviewed worktree.

3. Verify the file exists before running it — if no candidate from the trusted set above resolves, abort with error: review-anvil-pr/scripts/pr-helper.sh not found in any trusted skill root; reinstall via 'npx skills add mrshu/agent-skills --skill review-anvil-pr'.

The primary contract is "the script is ./scripts/pr-helper.sh relative to this SKILL.md." When the host doesn't expose that path, the user-level fallback is a recovery mechanism — but it is not a substitute for the host exposing skill-file paths, and project-scoped paths must never be searched.

2. Init

bash <helper-path> init "<locator>"     # explicit form
bash <helper-path> init                 # auto-detect from current branch

If the user supplied a locator (URL or <owner>/<repo>#<N> slug), pass it as the argument. If they didn't, invoke init with no argument — the script will run gh pr view --json url to find the PR associated with the currently checked-out branch and use that as the locator. The script aborts with a clear message if no PR is found.

On success, the script prints these KEY=VALUE lines on stdout:

HOST=github.com
OWNER=acme
REPO=widgets
N=137
RUN_ORDINAL=3
HEAD_SHA=<the PR head commit at review time>
MARKER=<uuidv4>
REPORT_PATH=<absolute-path>/.review-anvil/final-report-<uuidv4>.md
TITLE=<PR title>

If the locator was auto-detected, the script also prints auto-detected PR: <url> to stderr before the KEY=VALUE block, so the agent can echo that to the user before proceeding.

Capture all values, including RUN_ORDINAL. Echo to the user: review target: $HOST/$OWNER/$REPO#$N — $TITLE.

On non-zero exit, surface the script's stderr verbatim and stop. Do not dispatch reviewers.

3. Activate the engine

Activate the review-anvil skill with this argument string (extra user args go between the pinned params and the rounds default):

commit_mode: none, target: <locator>, report_path: <REPORT_PATH>, run_ordinal: <RUN_ORDINAL>, <extra-user-args>, adversarial: auto, rounds: 1

The user may override rounds: or adversarial: in their args (they are defaults, not pins). They cannot override the observed value of run_ordinal, or the commit_mode, target, and report_path pins; the step-0 segment-rejection above blocks override attempts.

RUN_ORDINAL comes from the init preflight. When it is a positive integer, the engine includes the corresponding RUN segment in new provenance IDs. The value unavailable makes the engine emit IDs without the RUN segment; degraded history must not invent a run number.

The engine's default reproduction: auto runs before adversarial review and reproduces uncertain material findings in one batched confidence pass. The user may pass reproduction: off for speed, but unreproduced single-reviewer medium+ findings, deletion/high-risk findings, and orchestrator-uncertain findings must stay Deferred rather than becoming inline/actionable PR comments.

The default adversarial: auto lets the engine choose off, challenge, targeted, or strict after normal synthesis. The user may also pass adversarial: off|challenge|targeted|full|strict. Adversarial review stays read-only: it attacks candidate findings and would-apply plans before the report is posted, so false positives can be dropped and harmful/bloated/tech-debt-heavy fixes can be deferred instead of turned into inline comments. Unresolved critical/high adversarial disputes and disagreement_policy=comment material disputes force the review event to COMMENT rather than APPROVE. If the user explicitly passes adversarial: off, the engine must write {"event":"COMMENT","adversarial_mode":"off", "approval_allowed":false} to .approval.json; unchallenged LLM review should not satisfy branch protection by accident.

Provide $HEAD_SHA to the engine for its .approval.json head_sha field — the posting helper uses it to downgrade a stale APPROVE (PR head moved mid-run) to a COMMENT.

The engine runs the review loop, writes the final report to <REPORT_PATH> (on failure paths too), and prints that path on its last output line. Before posting, if <REPORT_PATH>.followups.json exists, read it and surface its entries to the user (the helper deletes it after a successful post; auto_approved entries are the only ones automation may file issues for, after a duplicate search).

4. Post

bash <helper-path> post "$HOST" "$OWNER" "$REPO" "$N" "$MARKER" "$REPORT_PATH"

The script chooses the GitHub review event from <REPORT_PATH>.approval.json (APPROVE or COMMENT; default COMMENT if absent) and then posts the report:

• Approval / hybrid review. If the decision is APPROVE, the helper submits a GitHub approval review. If <REPORT_PATH>.inline.json is non-empty, its comments are included as non-blocking findings or suggestions; by default the helper posts critical/high/medium inline comments and leaves lower-severity items self-contained in the top-level body unless REVIEW_ANVIL_INLINE_MIN_SEVERITY is lowered. Otherwise the approval has only the top-level body. If GitHub rejects the inline anchors but accepts a body-only approval, the helper puts those inline bodies under the same collapsed Finding details section before approval so no action disappears. Use this when there are no critical/high actionable in-scope findings; medium-and-lower issues are posted but left to the author. If GitHub rejects the approval (most commonly: you cannot approve your own PR), the helper downgrades to a comment review, appends a note to the report explaining the downgrade, and keeps cascading down to the top-level fallback — a failed approval never costs the report. An unexpected or malformed approval.json likewise defaults to COMMENT, never to APPROVE.
• Comment review. If the decision is COMMENT and <REPORT_PATH>.inline.json exists and is non-empty, the script assembles a PR review payload ({event: COMMENT, body: <report>, comments: [...]}) and submits it via gh api /repos/{O}/{R}/pulls/{N}/reviews. This produces ONE review event in the PR timeline with a top-level summary body AND inline review comments anchored to specific files+lines — the native GitHub review UX. The API response's html_url is used directly (no marker lookup needed).
• Top-level fallback. If the decision is COMMENT and <REPORT_PATH>.inline.json is absent or empty (no findings had file+line), or if the PR-review API call fails (most common cause: reviewer-supplied line numbers aren't in the PR's diff), the script appends the processed inline bodies under one collapsed Finding details section before posting gh pr comment --body-file <REPORT_PATH>. It then recovers the URL via paginated marker lookup with one retry for read-after-write lag. This keeps the summary readable while preserving the only copy of each detailed diagnosis and request.

In all paths, the marker UUID is prepended to the report body (idempotently — retries don't stack markers) before posting, so URL recovery remains possible even on the fallback path. An APPROVE decision is additionally checked against the PR's current head SHA and downgraded to COMMENT if the PR moved since the review.

GitHub comment shape. The engine writes one headingless line containing one or two neutral detection sentences, with no decision label or review mechanic. Every active finding stays in a collapsed fixed table showing severity, location, complete detail, and the requested or suggested change. Detailed facts and requested work also live in inline comments when GitHub can anchor them. Review context, prior feedback, changes, and dispositions are collapsed; the review-anvil footer is the absolute final nonblank line. The helper posts that body without shortening it. On a top-level fallback it inserts otherwise-unpublished inline bodies and its idempotency marker before the footer under one count-free collapsed Finding details section. If GitHub rejects an unusually large payload, posting fails with the report left at <REPORT_PATH> so the running agent can rewrite it without dropping facts or actions.

Inline comment shape. Before submitting a PR review, the helper filters <REPORT_PATH>.inline.json. Inline comments default to critical/high/medium findings (REVIEW_ANVIL_INLINE_MIN_SEVERITY=medium); lower-severity findings remain self-contained in the top-level report. Each new body keeps the diagnosis as prose, labels requested work, and ends with hidden id, severity, and area metadata. The helper strips helper-only JSON fields before calling GitHub, inserts any safe exact suggestion and reintroduced-prior-feedback marker before the finding metadata, and keeps the finding marker as the final line.

The helper-only "severity" must match the terminal marker severity exactly; the helper aborts before filtering or posting when they disagree. A present but unrecognized helper severity also aborts; an absent helper field may use the terminal marker during migration.

Prior-feedback continuity. Before review, the engine fetches every root review thread with open/resolved/outdated state plus findings from earlier review-anvil review bodies and fallback comments. Reviewers must account for every ledger item; GitHub resolved means only that the discussion closed, not that the code was proven fixed. Immediately before posting, the helper refreshes this paginated history. If that refresh would remove, demote, or suppress an item from a compact report, posting fails closed and leaves the artifacts for a rerun so the visible summary can be rendered from the refreshed inventory; the helper never leaves a stale summary over a changed finding set. Legacy report forms retain compatible duplicate suppression. Different canonical IDs remain distinct, while path-and-text matching remains available when one side has no comparable ID. Delivery downgrade notes stay inside collapsed Review context.

Only the PR author resolving a GitHub review thread creates author-resolved status. This requires the API-confirmed resolvedBy identity to match the PR author; ordinary thread resolution remains resolved and is revalidated.

Scope discipline. The posted review should separate actionable in-scope findings from obvious pre-existing issues. Findings unrelated to the PR's stated purpose should appear, at most, under "Out-of-scope follow-ups" as separate-PR work and should not be emitted as inline actionable comments. Follow-ups are auto-approved only when they are confirmed, high-confidence critical/high (or clearly reproducible medium), not product/style decisions, not already tracked/dismissed, and separable from the current PR; ambiguous ones remain needs_triage.

Cleanup on success. After a successful post (comment or approval), the helper removes <REPORT_PATH>, <REPORT_PATH>.inline.json, <REPORT_PATH>.approval.json, and <REPORT_PATH>.followups.json, then removes the self-ignored parent directory when no other report artifacts remain. Retained proof bundles live in a separate host-created private directory outside the worktree and are unchanged. On any abort (die), report artifacts are also left in place so the user can inspect or post manually.

5. Report back

Surface the URL (or posted (URL unavailable)) to the user. If the helper script exited non-zero from post, surface its stderr; the report still exists on disk at <REPORT_PATH> for manual posting.

Examples

• "Review the PR I'm on and post the result back." — user is checked out on a PR branch. Agent invokes init with no locator; helper detects the PR via gh pr view.
• "Review https://github.com/acme/widgets/pull/137 with a focus on security." — explicit URL locator; extra arg focus: security flows through to the engine.
• "Review acme/widgets#42 and use 2 rounds of reviewer redundancy." — slug locator; rounds: 2 overrides the preset's rounds: 1 default.
• "Review acme/widgets#42 with adversarial: targeted." — force targeted adversarial review after normal synthesis.
• "Review acme/widgets#42 with adversarial: off." — skip adversarial review and post COMMENT-only feedback.

Constraints

• Requires gh, uuidgen, jq (a real binary — gh's --jq is built-in gojq and doesn't count), and uv (preferred; falls back to python3) for PR-feedback history handling. init preflights all of these so a missing dependency fails before the expensive review, not after.
• Environment switches honored by the helper: REVIEW_ANVIL_NO_APPROVE=1 (never submit an approval), REVIEW_ANVIL_POST_INFRA_FAILURES=1 (manual-debug escape hatch that allows posting infrastructure-failure reports; default is to refuse them so watchdogs retry instead of notifying authors), REVIEW_ANVIL_SKIP_DISMISSED=1 (legacy name: skip the full PR-history lookup for hosts without GraphQL access — degraded mode that also forces COMMENT), REVIEW_ANVIL_DISMISSALS=<path> (local-suppressions file, default ~/.review-anvil/dismissed-findings.json; record entries with pr-helper.sh dismiss <host> <owner> <repo> <n> <path> <pattern> [<reason>]), REVIEW_ANVIL_INLINE_MIN_SEVERITY=<critical|high|medium|low|nit> (minimum severity posted inline; default medium), and REVIEW_ANVIL_ENABLE_SUGGESTIONS=0 (disable helper-added GitHub suggestion blocks).
• An APPROVE decision submits a real GitHub approval from your authenticated gh account. It counts toward branch-protection required reviews and reads to collaborators as your judgment — while the gate behind it is the engine's LLM classification. If that posture isn't acceptable for a repo or org, pass approve: never (or "never approve" / "comment only") and the run always posts plain COMMENT reviews. REQUEST_CHANGES is deliberately unsupported: blocking someone's merge on LLM judgment is a different risk class from commenting or approving.
• What lands on the PR has passed the engine's reproduction/verification gates: uncertain medium+ findings are checked against the actual reviewed snapshot before posting. When a trusted proof_runner is configured, behavior claims may use retained executable probes run with network disabled, source and proof inputs read-only, filesystem reads restricted to source/proof/runtime inputs, writes restricted to the proof runtime directory, runner-authored results, a sanitized environment, and bounded resources. When execution is unavailable or a finding cannot be confirmed, the report says what proof is missing and sets the item aside rather than presenting it as actionable. False positives posted to a colleague's PR burn trust — the engine treats precision as the product.
• When adversarial: is enabled, the posted report should include only the final verdict summary and survivor findings. The adversarial transcript stays out of GitHub; its effects are folded into dropped findings, deferred disproportionate fixes, hardened fix paths, stripped suggestion blocks, and approval downgrades.
• Read-only by design — the PR's branch may not be checked out locally, and pushing fix commits to a PR you don't own is rarely the intent. If you want to fix-and-commit on a PR you have checked out, activate review-anvil directly with target: branch (your checked-out PR branch) and commit_mode=per_fix — the local working tree becomes the source of truth and the diff against the merge base is unambiguous.
• Supports github.com and GitHub Enterprise — the script extracts the host from the URL and sets GH_HOST internally for all gh invocations.
• Bare-integer PR locators are rejected — pass a URL or <owner>/<repo>#<N> slug to be unambiguous about repo identity.

Recovery: orphaned artifacts

If the orchestrator dies between the engine finishing and the post step, report artifacts remain under the artifact-local, self-ignored .review-anvil/ directory. Re-run step 4's post with the captured values to publish them: the helper's head-SHA check downgrades a stale APPROVE if the PR moved in the meantime, and the marker lookup prevents duplicate posts after partial success. Successful posting removes transient report artifacts but deliberately keeps proof bundles in their separate host-created private directory. Delete retained proof bundles manually when they are no longer useful.

Pairing

This preset depends on the review-anvil engine being available in the same agent. Both skills ship in the same plugin and should be installed together (npx skills add mrshu/agent-skills --skill review-anvil --skill review-anvil-pr, or just --all).