Review pr

Review Pull Request

Review one immutable GitHub pull-request snapshot. The workflow is read-only: it never submits a GitHub review, approval, change request, comment, Slack message, Jira mutation, checkout change, or other external action. No GitHub review is ever submitted by this skill.

Usage

/review-pr                                      # current branch
/review-pr 123                                  # current-repository shorthand
/review-pr owner/repo#123                       # repository-qualified
/review-pr https://github.com/owner/repo/pull/123  # PR URL
/review-pr owner/repo#123 --automation --premium-established --expected-head SHA

Accept a PR URL, owner/repo#number, a numeric current-repository shorthand, or no selector. A qualified selector never derives repository identity from the current working directory.

Optional controls:

• --expected-head SHA — require the selected immutable head.
• --checkout PATH — consider this local checkout, but use it only after exact verification.
• --automation — return the machine-readable contract below and never ask a question.
• --premium-established — assert that the caller selected the premium route before automation.
• --deadline-seconds N — total attended review budget; default 300 seconds. Record one absolute stop deadline at invocation, pass only the remaining seconds to each collector call, and return partial evidence when the budget expires.

1. Establish the premium route

This skill is model-tier: premium.

For a manual invocation below the premium tier, use AskUserQuestion once:

• Continue here — accept reduced depth for this run.
• Stop — switch model or rerun in a premium session.

Skip the question when the user explicitly selected the current model.

For --automation, the skill must not prompt. Require --premium-established and confirm the current route satisfies the premium tier. If either condition fails, return status: failed, reason: premium-route-unavailable, and no verdict. Frontmatter alone is not route attestation.

2. Collect one qualified snapshot

Run the collector once before analysis:

~/.agents/skills/review-pr/scripts/gh-pr-snapshot.py \
  'owner/repo#123' \
  --expected-head HEAD_SHA_IF_SUPPLIED \
  --checkout CHECKOUT_IF_SUPPLIED \
  --timeout REMAINING_SECONDS \
  --pretty

Omit absent options. With numeric or no selector, the collector uses the current checkout only to resolve the shorthand, then passes explicit owner/repository to every remote request.

The collector returns canonical repository/PR identity, node ID, base/head refs and SHAs, bounded file patches, exact-head CI rollup, normalized feedback, a review-state key, checkout verification, limits, and errors. It disables paging and lazy Git fetching, applies one deadline and command-output cap, and rechecks base/head identity after collection.

Gate on its status:

• complete with reviewReady: true — continue.
• partial — name every unavailable/truncated source; do not issue a definitive verdict.
• stale — stop and report the expected and observed revisions; never present mixed-SHA evidence.
• failed — stop and report the bounded error; do not infer that missing evidence is empty.

Draft or closed/merged state remains explicit in target; do not treat it as an open review.

3. Use local code only after exact checkout proof

A matching checkout is optional. Local repository reads are permitted only when checkout.available is true. That means the origin matches the selected repository, the working tree is clean, and local HEAD exactly matches the PR head SHA. Anchor every Read, Grep, or Glob path under checkout.path.

When verification fails, state Local repository search unavailable with the collector's reason. Use only the bounded remote patches and metadata. Never search the workspace root or unrelated cwd, and never switch branches, fetch, reset, clean, create a worktree, or edit files.

4. Read feedback before forming an opinion

Read evidence.feedback.records before analyzing the patches. Preserve stable identity, updateKey, stateKey, source, lifecycle, author, targets, and path/line data. Inspect evidence.feedback.partial and its errors before treating absence as none.

Build the unresolved list from:

• unresolved, non-outdated inline-review records;
• current CHANGES_REQUESTED reviews only when target.reviewDecision still reports changes requested;
• substantive current review summaries or conversations whose request remains unmet.

Treat approvals, dismissed/outdated/resolved records, self-authored messages, and automated status noise separately. Bot findings require the same independent validation as human findings.

5. Load Jira context when linked

Find the first Jira key in title, body, or head branch using [A-Z][A-Z0-9]{1,9}-[0-9]+.

• No key: record jira.status: not-linked and continue without an AC checklist.
• Key found and lookup succeeds: extract summary, description, status, issue type, and acceptance criteria with the read-only Jira get tool.
• Key found but Jira is unavailable, malformed, or missing the acceptance field: record jira.status: unavailable, include the error, and never claim requirements are satisfied.

Do not use any Jira mutation tool.

6. Analyze the exact-head evidence

Use target, evidence.files, feedback, CI state, and verified local reads when available.

Before Jira lookup and before each analysis phase, check the one invocation deadline. On expiry, return partial with budget-expired; do not start another tool call. The caller should also impose its normal turn/runtime budget so interruption does not depend on model compliance.

For each changed file, assess:

• alignment with linked acceptance criteria;
• correctness, security, compatibility, and scope;
• test coverage including happy, sad, and edge paths;
• whether current patches address unresolved feedback;
• deletions and repository-wide references, but only when checkout verification permits the search.

If file patches, feedback, checks, Jira requirements, or repository-wide evidence needed for a claim are unavailable, make the limitation explicit. Missing evidence is never evidence of absence.

7. Recheck the immutable revisions

Immediately before writing any verdict, run the fast verifier using the original snapshot SHAs:

~/.agents/skills/review-pr/scripts/gh-pr-snapshot.py \
  'owner/repo#123' \
  --expected-head ORIGINAL_HEAD_SHA \
  --expected-base ORIGINAL_BASE_SHA \
  --expected-state-key ORIGINAL_STATE_KEY \
  --verify-only \
  --timeout REMAINING_SECONDS

The state key covers PR lifecycle, draft/review decision, exact-head CI state, and stable feedback identities/update state. If verification returns anything except complete, return stale or failed and suppress the verdict. Never reuse approval from a previous invocation or head SHA.

8. Render unresolved comments before the verdict

Every human-readable review must include this exact section before any assessment or verdict:

### Unresolved Reviewer Comments

- author — path:line — request — whether it remains valid at the reviewed head

If genuinely empty, emit:

### Unresolved Reviewer Comments

- None.

9. Output contract

Manual output

## owner/repo#123 Review

**Head:** {immutable head SHA}
**Base:** {immutable base SHA}
**Snapshot:** complete
**Jira:** {key and summary | Not linked | Unavailable}
**CI:** {exact-head rollup state}
**Local checkout:** {verified path | unavailable reason}

### Changes Overview
- ...

### Unresolved Reviewer Comments
- ...

### AC Checklist
| AC | Status | Evidence |
|----|--------|----------|
| ... | pass/fail/partial | ... |

### Concerns
- ...

### Verdict
{Safe to merge | Needs changes | Needs discussion}

Verdict rules:

• Needs changes for unmet ACs, failing exact-head CI, or a valid blocking concern.
• Needs discussion for conflicting evidence or a substantive unresolved question.
• Safe to merge only when the snapshot is complete, exact-head CI succeeds, Jira ACs are met when linked, and unresolved comments are None..
• No definitive verdict for partial, stale, or failed snapshots.

Automation output

For --automation, emit one JSON object and no conversational prompt or surrounding prose:

{
  "schemaVersion": "review-pr/v1",
  "status": "complete|partial|stale|failed",
  "reason": null,
  "target": {
    "repository": "owner/repo",
    "number": 123,
    "nodeId": "...",
    "headSha": "...",
    "baseSha": "...",
    "stateKey": "..."
  },
  "changesOverview": [],
  "evidence": {
    "snapshotComplete": true,
    "checkout": "verified|unavailable",
    "checkoutReason": null,
    "jira": "available|not-linked|unavailable",
    "jiraKey": null,
    "jiraSummary": null,
    "ci": "SUCCESS|FAILURE|PENDING|UNKNOWN",
    "errors": []
  },
  "unresolvedComments": [],
  "acChecklist": [],
  "concerns": [],
  "verdict": "safe-to-merge|needs-changes|needs-discussion|null"
}

reason is null for complete results and names the bounded failure/stale reason otherwise, including premium-route-unavailable. Before snapshot identity is available, target fields are null rather than fabricated. changesOverview contains the complete bounded changes summary used by the manual report. checkoutReason explains unavailable local evidence. jiraKey is populated when a key is linked; jiraSummary is populated only when lookup succeeds. Each unresolved comment, AC row, and concern retains its concise evidence so an automation caller can render the same complete report without re-running analysis.

The watcher may consume a verdict only when status is complete, the final revision recheck succeeded, and verdict is non-null. This output authorizes no GitHub review or other external communication.