review-pr

name	review-pr
description	Prepare a GitHub pull request branch locally, add the contributor fork as a remote when missing, and produce a rigorous code review based on the PR description, linked issues, and actual code changes.

Review PR Workflow

Use this skill when the user asks to review a GitHub pull request, check out a PR branch locally, or prepare a review from a PR link such as tisfeng/Easydict#1173 or https://github.com/tisfeng/Easydict/pull/1173.

Required Input

The user must provide one PR reference:

• GitHub URL: https://github.com/<base-owner>/<base-repo>/pull/<number>
• Shorthand: <base-owner>/<base-repo>#<number>
• PR number only, when the current checkout belongs to the target repository

If the PR reference is missing or ambiguous, ask for it before changing Git state.

Hard Rules

• Keep the local branch name exactly the same as the PR head branch name.
• Name the contributor remote exactly as the PR head repository owner login.
• Do not overwrite, delete, rename, rebase, reset, or force-update an existing local branch.
• Do not push anything while preparing or reviewing the PR.
• Do not stash or discard local changes automatically. Stop and ask the user if the worktree is dirty before preparing or switching branches.
• If a remote with the intended contributor name already exists but points to a different repository, stop and ask the user how to proceed.
• Do not review from the PR description alone. Inspect the linked issues, changed files, actual diff, and relevant surrounding code.
• Follow the repository's normal review stance: lead with PR context, then findings. Prioritize bugs and regressions, include file and line references, then list open questions, verification, and a short summary.

Step 1: Check Worktree and Resolve PR Metadata

Check the current worktree before changing Git state:

git status --short --branch

If the worktree has uncommitted changes, stop and ask the user before preparing or switching branches.

Collect PR metadata with GitHub CLI before branch preparation. For a GitHub URL or <owner>/<repo>#<number> shorthand, convert it to <number> --repo <owner>/<repo> when running manual gh commands. For example, owner/repo#123 becomes gh pr view 123 --repo owner/repo:

gh pr view <number> [--repo <base-owner>/<base-repo>] \
  --json number,title,url,body,baseRefName,headRefName,headRepository,headRepositoryOwner,closingIssuesReferences

Extract these fields:

• headRepositoryOwner.login, for the remote name.
• headRepository.name, for the fork repository name.
• headRefName, for the PR branch name.
• baseRefName, for the base branch used during diff review.
• closingIssuesReferences, for issue context.

Do not add or update the contributor remote manually in the normal path. Let the helper script prepare the remote, fetch, local branch, and upstream tracking.

Step 2: Prepare the PR Branch

Use the bundled helper script as the default branch preparation path:

bash .agents/skills/review-pr/scripts/prepare-pr-branch.sh <pr-ref>

The helper script:

• Parses a GitHub PR URL, <owner>/<repo>#<number>, or PR number.
• Reads the PR head owner, fork repository, and branch from gh pr view.
• Adds the contributor remote only when missing.
• Fetches the exact PR head branch into refs/remotes/<owner>/<branch>.
• Creates or switches to a local branch whose name exactly matches the PR head branch, and skips switching when that branch is already current.
• Sets the local branch upstream to <owner>/<branch>.
• Uses fast-forward-only integration when the local branch already exists.

Use manual remote, fetch, and switch commands only as a fallback when the helper script is unavailable or fails for a reason unrelated to PR state. In fallback mode, normalize URL and shorthand PR refs the same way as Step 1, add the contributor remote only when missing, verify any existing same-name remote points to the expected fork, fetch the exact head branch, create or switch to a local branch with the exact PR head branch name, and set upstream tracking to the contributor remote branch.

After it finishes, verify the checkout:

git branch --show-current
git status --short
git branch -vv

If the branch is dirty, detached, missing upstream, or not named exactly like the PR head branch, stop and fix that state before reviewing.

Step 3: Review Context

Read PR context and issue context first, using the normalized PR number and --repo arguments from Step 1 when needed:

gh pr view <number> [--repo <base-owner>/<base-repo>] \
  --comments \
  --json number,title,url,body,baseRefName,headRefName,files,commits,closingIssuesReferences,comments,reviews

For every linked issue in closingIssuesReferences, inspect the issue body and comments:

gh issue view <issue-url-or-number> --comments

Then inspect the code changes against the PR base branch. Use origin as <base-remote> only after confirming it points to the PR base repository. If it does not, use the correct base repository remote or stop and ask the user. Fetch the base branch from the base repository remote if necessary, then compare with three-dot diff:

git fetch <base-remote> <base-branch>
git diff --stat <base-remote>/<base-branch>...HEAD
git diff --name-status <base-remote>/<base-branch>...HEAD
git diff <base-remote>/<base-branch>...HEAD

Read relevant surrounding source files, tests, configuration, generated files, and documentation before making claims. Use rg for fast code search.

Review Focus

Check the PR against the actual problem it claims to solve:

• Does the implementation fully address the PR description and linked issues?
• Are there behavior regressions, edge cases, concurrency issues, persistence mistakes, localization gaps, or platform-version problems?
• Are public contracts, model names, defaults, migrations, and UI states still coherent?
• Are tests or manual verification sufficient for the changed behavior?
• Does the code match local project patterns, naming, style, and architecture?
• Are unrelated refactors, generated churn, or accidental changes present?

Do not run xcodebuild during PR review unless the user explicitly asks for a local build. When validation status matters, inspect PR checks instead:

gh pr checks <number> [--repo <base-owner>/<base-repo>]

Always run lightweight local checks such as git diff --check when they are relevant.

Output Format

Write the final review in the user's preferred system language unless the user asks otherwise.

Preferred system language means the first language in macOS AppleLanguages. Read it with defaults read -g AppleLanguages and use the first list entry. If the current agent environment cannot read that value, write in the language the user is already using in the current conversation.

Keep section headings, PR Context subheadings, and priority labels exactly as written. Use this structure exactly:

## PR Context

**Purpose and Scope**

Describe what the PR is trying to achieve, which issue or workflow it targets,
and the boundary of the change.

**Key Changes**

Describe the main implementation changes and the important code paths touched.

**Review Focus**

Describe the expected impact, important risks, compatibility concerns, or areas
reviewers should inspect.

---

## Findings
- [P1] path:line - Describe each issue, trigger condition, risk, and suggested
  change.
- If there are no findings, say so clearly.

## Open Questions
- List correctness-affecting questions, or say clearly that there are no
  meaningful open questions.

## Verification
- List commands and checks performed, or explain why validation was not run.

## Summary
Short neutral summary of the overall review result without repeating the PR
context.

Build PR Context from the inspected PR title and body, linked issues, actual diff, and relevant surrounding code. Do not merely restate the PR description. Write one natural paragraph of 2-4 sentences under each subheading.

Priority values:

• P0: data loss, crashes, security flaws, or broken core workflows.
• P1: likely user-visible regression or incorrect behavior.
• P2: edge-case bug, missing compatibility, or incomplete issue coverage.
• P3: maintainability, clarity, or test/documentation gap worth fixing.