review-pr

Review a GitHub pull request for correctness, security, design, and maintainability. Default mode is remote (posts comments to GitHub). Pass mode=local to display findings without posting.

Parameters

• pr — PR number or URL (optional; auto-detected from current branch if omitted)
• mode — remote (default) or local
• auto — true or false (default false). When true, skip the operator confirmation gate (Step 4) and proceed directly to posting/displaying. Use COMMENT as the review event (never REQUEST_CHANGES or APPROVE without a human). Intended for build-loop autonomous invocation.

0. Identify the PR

Detect from context (current branch, parameter, or URL). Prefer:

gh pr view --json number,url,baseRefName,headRefName

Fall back to asking the user.

1. Fetch the diff and PR metadata

gh pr diff NUMBER
gh pr view NUMBER --json title,body,files,additions,deletions,commits,isDraft,headRefOid

Fetch existing review comments to avoid duplicating feedback:

gh api graphql -f query='
  query($owner:String!,$repo:String!,$pr:Int!) {
    repository(owner:$owner,name:$repo) {
      pullRequest(number:$pr) {
        reviewThreads(first:100) {
          pageInfo { hasNextPage endCursor }
          nodes {
            id
            isResolved
            isOutdated
            path
            line
            viewerCanResolve
            comments(first:30) {
              nodes {
                id
                databaseId
                body
                author { login }
                path
                line
                originalLine
                createdAt
              }
            }
          }
        }
      }
    }
  }' -f owner=OWNER -f repo=REPO -F pr=NUMBER

1.5. Scope the review (large PRs)

If the PR touches more than ~30 files, prioritise:

Use the file list from gh pr view NUMBER --json files to sort by additions + deletions. Start with the highest-churn non-generated files.

If the PR is too large to review meaningfully (100+ files with substantive logic changes), say so. Recommend the author split it, and offer to review a subset they nominate.

2. Understand the change

Before looking for problems:

1. Read the PR title, description, and commit messages to understand intent.
2. Scan the full diff to grasp the shape of the change.
3. Read surrounding source code for files with non-trivial changes.
4. Identify the type of change: feature, bugfix, refactor, config, docs, etc.

Do not start flagging issues until you understand what the author was trying to achieve and why.

If the PR description is empty or uninformative:

1. Infer intent from commit messages and the diff itself.
2. Note the gap in triage output: "PR has no description — review is based on code and commit messages only. Risk of misunderstanding intent."
3. If intent remains unclear after reading the code, ask the user before proceeding.

3. Triage — pragmatic, not pedantic

Review changed files (using the priority order from step 1.5 for large PRs). For each potential finding, classify it:

Ground rules:

• If it works, is readable, and follows project conventions — don't comment.
• Challenge your own findings: "Would I mass-reject a PR over this?" If no, consider skipping.
• Group related issues. Don't leave 5 comments about the same pattern — leave one with context.
• Acknowledge what's done well when something is genuinely good.
• Never auto-approve and never block for style alone.

4. Present triage for confirmation

Before posting anything (remote mode) or finalising (local mode), present findings:

## PR Review Triage — PR #123: <title>

**Critical (must fix):**
- `src/auth.ts:42` — JWT secret read from env without fallback; server crashes on missing var
- `src/db.ts:88-91` — Raw SQL interpolation -> SQL injection risk

**Concern (worth discussing):**
- `src/api/handler.ts:15-30` — New retry logic has no backoff; could hammer downstream service

**Nit (minor, pattern-level):**
- Inconsistent error message format across 4 new handlers (some use template literals, some concatenation)

**Positive:**
- Clean separation of validation logic into its own module
- Good test coverage on the happy path

**Skipped:** 3 minor style items — not worth comment noise.

If auto=false (default): Wait for user confirmation before proceeding. The user may reclassify findings, drop items, or add context.

If auto=true: Log the triage for auditability (include it in the PR summary comment later), then proceed immediately — do not wait for confirmation.

5a. Remote mode — post the review

After confirmation, resolve OWNER, REPO, and the latest commit SHA:

gh repo view --json owner,name --jq '"\(.owner.login) \(.name)"'
COMMIT_SHA=$(gh pr view NUMBER --json headRefOid --jq '.headRefOid')

Choose the review event based on confirmed findings:

Default to COMMENT when unsure. Never auto-approve or auto-request-changes without user confirmation. For draft PRs, always use COMMENT regardless of findings.

If auto=true: Always use COMMENT regardless of findings. The operator reviews the PR after the autonomous cycle completes — they decide whether to request changes or approve.

Submit a single review with inline comments using --input -:

jq -n \
  --arg event "COMMENT" \
  --arg body "$(cat <<'BODY'
## Review summary

**Critical:** 2 items flagged (see inline)
**Concerns:** 1 item flagged (see inline)
**Overall:** Good direction, a few items to address before merge.
BODY
)" \
  --arg sha "$COMMIT_SHA" \
  '{
    event: $event,
    body: $body,
    commit_id: $sha,
    comments: [
      {path: "src/auth.ts", line: 42, side: "RIGHT",
       body: "**Critical:** JWT secret has no fallback — server will crash on missing env var. Consider a startup check or default."},
      {path: "src/db.ts", line: 91, side: "RIGHT", start_line: 88, start_side: "RIGHT",
       body: "**Critical:** Raw SQL interpolation -> SQL injection risk."}
    ]
  }' \
| gh api repos/OWNER/REPO/pulls/NUMBER/reviews --method POST --input -

For multi-line comments, include both start_line/start_side and line/side. Use the category prefix (Critical, Concern, Nit) in each comment body.

After posting, confirm to the user what was posted and provide the PR URL.

5b. Local mode — display only

Present the full review in chat using the same format as the triage in step 4, but with full comment bodies for each finding. Nothing is posted to GitHub.

End with:

Local review complete. Say "post it" to submit this review to GitHub (I'll confirm the event type first), or adjust findings.

If the user says "post it":

1. Confirm the review event type (see event table in step 5a).
2. Execute the remote posting flow from step 5a using the already-triaged findings.
3. Do not re-analyse the diff.

Notes

• Respect the author's context. They may know things you don't. Frame concerns as questions when uncertain: "Is there a reason this doesn't use...?"
• Don't duplicate existing feedback. Check existing review threads before posting. If someone already raised it, skip or +1 briefly.
• Check CI before reviewing. If CI is red, note it but don't spend time reviewing code that may change. Tell the user: "CI is failing — worth fixing that before a deep review."
• Forks. gh pr diff and gh pr view work across forks transparently. The headRefOid from gh pr view is the correct commit for inline comments regardless of fork origin.