PR Reviewer Skill

Read and follow agent-conduct, implementation-principles, testing-principles, code-smells, subagents, and the project's conventions skill before starting. Use pr-resolver for GitHub PR review comments plus CI/Copilot loops. subagents owns delegation: agent choice, briefing, skill discovery, and error handling. This skill covers only the PR-review procedure.

You examine the diff, perform a thorough review, and fix issues by delegating to implementor subagents. Establish the outermost queue owner using bugfix routing before starting; inherit a caller's owner when nested.

Input

• Base reference (optional): branch/SHA. Resolution order: caller-provided -> active PR base.ref -> agent-conduct Git Safety fallback.
• Spec document (optional): path for conformance checking.
• Focus areas (optional): specific files or concerns.

Procedure

GitHub CLI prerequisite (mandatory)

Before resolving base or doing any diff/lint/test, verify gh is installed and authenticated:

if ! command -v gh >/dev/null 2>&1; then
  echo "GitHub CLI (gh) is not installed. Stop. Install gh from https://cli.github.com/manual/installation, then run: gh auth login" >&2
  exit 1
fi

if ! gh auth status >/dev/null 2>&1; then
  echo "GitHub CLI (gh) is not authenticated. Stop. Run: gh auth login. For non-interactive environments, set GH_TOKEN or GITHUB_TOKEN, then confirm with: gh auth status" >&2
  exit 1
fi

If either check fails, stop, with instructions on how to install and authenticate gh. Do not continue in local-only mode, silently skip PR data, use curl, rely on raw tokens directly, use VS Code GitHub tools, or use the web UI as a workaround.

0. Resolve base (mandatory)

Lock the review base before any diff/lint/test:

1. Caller-provided base, OR
2. PR base.ref (query via gh pr view --json baseRefName if needed), OR
3. With no PR or caller base, use the fetched base selected by agent-conduct Git Safety.

Hard rules: Never use repo default branch when a PR exists. Never diff before base is resolved. Emit Review base resolved: <base>. If PR exists but base.ref unavailable, stop and report failure.

1. Gather context

• Get current branch, collect git diff <base>...HEAD and git diff HEAD.
• Read full content of every modified file (not just diff hunks).

2. Check for open PR

Use gh pr view --json number,baseRefName,headRefName,url to check for an active PR. If there is an active PR, validate the resolved base matches PR base.ref. If there is no active PR, skip PR comment handling.

When an active PR exists, read all review comments via gh api (NOT the VS Code tool - it caps at 50 and misreports state):

gh api repos/{owner}/{repo}/pulls/{number}/comments --paginate

Note unresolved threads as additional review items.

3. Code review

For every changed file, assess:

• Quality: Apply all rules from implementation-principles and the project's conventions skill.
• Design: Match the changed code against code-smells. Each hit is a judgement call unless a convention or an implementation-principles rule makes it blocking.
• Bugs: races, resource leaks, off-by-one, nil derefs, goroutines without exit paths, missing await, unvalidated external data.
• Usability: Are features actually usable end-to-end (not just mocked)? Clear CLI help/error messages? Edge cases handled?
• Test quality: Meaningful assertions? Faithful mocks? Adequate coverage? Conforms to testing-principles and conventions?
• Unresolved PR comments: verify if current code addresses them.

4. Spec conformance (if spec provided)

Launch a reviewer subagent with the reviewer + conventions skill paths, spec path, and modified files list.

5. Run linters and tests

Use commands from the conventions skill. Note failures. Apply user-path verification to changed behaviour, refreshing affected proof after subsequent fixes.

6. Compile findings

Numbered list ordered by severity (bugs > quality > style). Each finding: file/lines, category, description, suggested fix. Apply bugfix routing to every finding; record independent issues before continuing and keep required gate blockers in the current work. If no current-branch findings remain, continue at step 8 for PR thread handling before completion.

7. Fix issues

For each finding routed to the current branch:

a. Launch an implementor subagent with: implementor + conventions + testing-principles skill paths, the specific finding (file, lines, description, fix), surrounding context, and "Fix this issue. Follow TDD cycle and testing-principles. Run linters. Confirm tests pass."

b. Verify the fix is correct and tests pass. Retry if needed.

c. If fixing addresses unresolved PR threads, reply (fixed - ...) and resolve each thread.

d. Commit each fix (single-line imperative message, max 72 chars). Batch purely cosmetic fixes into one style-cleanup commit.

8. PR comments

If there are unresolved PR threads, if step 7 fixes resolve PR threads, if checks need to be verified after a PR fix, or if the caller specifically asks to address PR review comments, switch to pr-resolver for thread triage, replies, resolution, and CI/Copilot push handling. Direct human requests are requirements; human questions and Copilot suggestions are review input that may be resolved with a clear no-code explanation when appropriate.

9. Complete or return to caller

After current-branch fixes and required PR work succeed, apply queue completion. A nested review returns pending references without processing them; the outermost owner drains them. A blocked review reports the pending references.

Rules

• Follow the rules in subagents (no direct fixes, no read-only agents for work that must change files or run tests).
• Route every finding; recorded independent handoffs are not review failures.
• One fix per commit (cosmetic batches excepted).
• Reply+resolve PR threads before committing fixes that address them.
• gh is mandatory. If it is not installed or authenticated, stop, with instructions on how to install and authenticate gh; do not attempt workarounds.
• Follow agent-conduct for pushes. This skill normally delegates PR push/check/review loops to pr-resolver.

Appendix: GitHub API Recipes

All commands require an installed and authenticated gh CLI. If gh is not installed or gh auth status fails, stop, with instructions on how to install and authenticate gh. Do not fall back to curl, raw token calls, VS Code GitHub tools, or the web UI.

Verify GitHub CLI

command -v gh >/dev/null 2>&1
gh auth status >/dev/null 2>&1

Fetch PR comments

gh api repos/{owner}/{repo}/pulls/{number}/comments --paginate

Root comments only:

gh api repos/{owner}/{repo}/pulls/{number}/comments --paginate \
  --jq '[.[] | select(.in_reply_to_id == null)] | .[] | "\(.id) \(.path) \(.body[:80])"'

Reply to thread

gh api repos/{owner}/{repo}/pulls/{number}/comments \
  -f body='fixed - <description>' -F in_reply_to=<comment_id>

Resolve thread (GraphQL)

Get thread node IDs:

gh api graphql -f query='{
  repository(owner: "{owner}", name: "{repo}") {
    pullRequest(number: {number}) {
      reviewThreads(last: 100) {
        nodes { id isResolved comments(first: 1) { nodes { databaseId path } } }
      }
    }
  }
}'

Resolve:

gh api graphql -f query='mutation {
  resolveReviewThread(input: {threadId: "{thread_node_id}"}) {
    thread { isResolved }
  }
}'