GitHub PR Review Guide

GitHub PR Review Guide

Usage guide for github-pr-review, grounded in its SKILL.md and README. This page is explanatory — the linked files are the contract.

What it reviews

An existing GitHub Pull Request's delta — by URL, or a PR number with unambiguous repository context. Someone else's PR, or the reviewer's own (self-review is allowed; see below).

Two delivery modes, same standard

• Passive — reads the PR, returns a report. No GitHub mutation.
• Active — may publish inline findings, a final summary, and submit Approve / Request Changes, subject to the authorization gate below.

Both apply identical review standards; only delivery differs.

Invoking it

review PR https://github.com/acme/app/pull/812
just review PR #812 and tell me what you find        → report only
review #812; block it if there are serious issues     → may Request Changes
review #812 and approve it if it's clean              → Approve only if independently authorized

The phrasing sets requested behavior, not trusted authorization — see below.

Analysis vs. GitHub mutation authority

These are two separate things, and the split is a durable governance feature of this Skill:

• The Skill always produces a full review and a mechanically derived verdict.
• Whether that verdict is submitted to GitHub as APPROVE / REQUEST_CHANGES is a separate, authorized decision. The default is non-mutating recommendation-only.
• APPROVE is submitted only in explicitly-authorized auto-action mode, under a trusted authorization signal independent of the reviewing agent, scoped to the exact invocation/repo/PR/HEAD/action. Natural-language requests ("approve if clean") are requested behavior, never authorization. Ambiguity fails closed to non-mutating.

Canonical: policies/review-action-authorization.md.

Self-review is allowed; self-approval is not

When the reviewer shares a controlling authority with the PR author (same identity, an alternate account/token, bot, service account, GitHub App, or nested agent), the full analysis still runs and reports a verdict — but no formal APPROVE / REQUEST_CHANGES event is ever submitted on that work. The result may be published as an informational COMMENT only. Canonical: policies/review-authority.md.

HEAD safety

The reviewed PR HEAD is recorded at the start and revalidated immediately before the final decision. A stale HEAD is never approved; a changed HEAD triggers re-review of the new delta first. Any trusted authorization is bound to the exact reviewed HEAD.

Re-reviewing after a push

When the same reviewer re-reviews and the previously reviewed SHA is known reliably, the review scopes to what changed since then and returns NO NEW DELTA if nothing did. Any ambiguity defaults to a full review. See Review-Context-and-Existing-Evidence and docs/features/delta-re-review.md.

Stacked / dependent PRs

When a PR's declared base is itself another open PR, the review detects the stack, derives the effective review base (the parent's current head), and scopes the Review Target to this layer's owned delta — the lower stack is read-only Repository Context, never an additional review target. See policies/stacked-pr-review.md.

Review-base policy compliance

Separately from stack topology above, the review also checks the stack's resolved root (the repository's actual default/target branch, or the PR's own declared base for a non-stacked PR) against the target repository's own review-base policy — never an intermediate stack layer's parent-PR base, which is the legitimate stacked-PR case above, not a violation. The required base is resolved from the target repository's own signals (an explicit statement in its instructions, else its configured default branch), never a hardcoded name, and the check is silent whenever that base — or an unresolved stack topology itself — can't be established reliably; it never guesses and never substitutes HEAD. A reliably established mismatch is reported as one blocking P0, naming both branches, before implementation findings. See How-the-Review-Model-Works and shared/policies/review-base-policy.md.

Checking runtime-validation evidence

Repository-backed checkout mode itself never executes anything — cloning PR code is not permission to run it. Separately, an optional runtime-validation capability may run one repository-declared test/lint command (or a targeted per-finding reproduction) inside a verified isolation boundary. Check the report's Validation section for whether it executed/failed/skipped/unavailable, and its sandbox or trusted-host provenance if it ran — see Feature-Runtime-Validation-Evidence.

What it never does

• Never merges, deletes branches, or edits implementation files.
• Never runs the target repository's own tests, linters, build, or hooks as part of repository-backed checkout mode itself — see "Checking runtime-validation evidence" above for the separate, optional capability that can.
• Never changes approval-count rules, stale-review settings, or bypass actors on branch protection; its only opt-in branch-protection action is adding its own single status as a required check.
• Maximum positive action is Approve.

Related feature pages

At-a-glance pages for capabilities this Skill supports: Feature-Runtime-Validation-Evidence · Feature-Requirement-Coverage · Feature-Delta-Re-Review · Feature-GitHub-Publication-and-Authorization · Feature-Human-Style-Review-Output. Full catalog: Feature-Pages.

Full contract

SKILL.md is the normative entry point; the canonical policy index is policies/github-review.md. This guide only summarizes them.

---

Wiki Page Map

Page	What it covers
Home	Wiki entry point: what the two Skills are and where to go next.
Getting-Started	First steps to package and run either Skill.
Choosing-a-Review-Skill	How to decide between local-code-review and github-pr-review.
How-the-Review-Model-Works	Concept-level walkthrough of the review pipeline shared by both Skills.
Architecture-Overview	Component-level map of how the repository's pieces fit together.
Specialist-Depth-Review	When and how a review goes deeper than its base pass.
Local-Code-Review-Guide	Usage guide for reviewing local, not-yet-PR'd Git changes.
GitHub-PR-Review-Guide	Usage guide for reviewing an existing GitHub Pull Request.
Review-Context-and-Existing-Evidence	How optional requirements/context and prior review evidence are supplied.
Feature-Pages	Index of per-feature capability pages and their shared template.
Feature-Delta-Re-Review	How a re-review scopes itself to only what changed since the last pass.
Feature-GitHub-Publication-and-Authorization	What a PR review publishes to GitHub and under what authority.
Feature-Human-Style-Review-Output	The senior-engineer-voice prose summary output option.
Feature-Requirement-Coverage	How supplied requirements are checked and reported as covered or not.
Feature-Runtime-Validation-Evidence	How a review can execute commands or reproductions as evidence.
Severity-and-Decision-Model	The P0/P1/P2 severity levels and how the merge decision is derived.
Packaging-and-Portability	How the Skills go from source repository to a standalone archive.
Development-Workflow	Contributor guide for working on this repository itself.
Benchmark-Testing	Orientation to this repository's own review-quality benchmark pipeline.
Repository-Documentation-Map	Where each concern's canonical, authoritative source lives.
AI-Code-Review-Landscape	Neutral snapshot comparing this project against other AI code-review products.
FAQ	Short, practical answers to common questions.