ericmjl/skills/gh-pr-code-review

PR code review (gh)

This skill guides a repeatable pull request review workflow using the GitHub CLI.

It emphasizes two-pass review (to find more issues), drafting comments before posting, and posting only after explicit user confirmation.

Usage

Use this skill when the user asks you to review a pull request and leave actionable feedback.

Inputs you should accept:

• PR number, PR URL, or branch name accepted by gh pr view / gh pr diff
• Optional repo override via -R owner/repo if not in a git checkout

Requirements

• gh authenticated (gh auth status)
• Permission to comment on the PR
• Optional but useful: jq

What it does

A code review in two passes, then a drafting and posting phase:

A) Pull down the PR diff and identify issues

B) Repeat the review, finding only new issues

C) Draft review comments but do not post yet

D) Prioritize comments by criticality:

• critical: correctness/security/data loss/broken API/test failures
• optional: maintainability/performance/edge cases/docs/test gaps
• trivial: nits/style/micro-optimizations (do not show by default)

E) Show only critical and optional items to the user. Then, if (and only if) the user explicitly confirms, post:

• inline (line-level) review comments where anchoring is unambiguous
• a single summary timeline comment containing only critical + optional items

How it works

0) Gather PR context

1. Identify the PR. Prefer a PR number or URL.
2. Fetch PR metadata (including the head commit SHA):

gh pr view <PR> --json number,title,url,baseRefName,headRefName,headRefOid,files,additions,deletions

1. Fetch the diff (the primary review artifact):

gh pr diff <PR> --color=never

Optional: check CI signal while reviewing:

gh pr checks <PR>

1) Stage A: first-pass review

Review the diff and record issues as structured items. For each issue capture:

• severity: critical | optional | trivial
• path: file path when applicable
• side: RIGHT (new code / additions / context) or LEFT (deletions)
• line: line number in the diff blob when you can anchor reliably
• body: the draft comment text (short, actionable)

Focus this pass primarily on:

• correctness and logic errors
• security risks
• API breaks
• data loss / irreversible behavior
• missing or failing tests

2) Stage B: second-pass review (new issues only)

Re-review the same diff from scratch with a different lens:

• edge cases
• performance and algorithmic complexity
• naming, clarity, ergonomics
• documentation and user-facing behavior
• consistency with project conventions

Critical rule: do not repeat issues from stage A. Only append genuinely new issues.

3) Stage C: draft comments (do not post)

Convert each issue into a comment draft that is ready to paste/post:

• one idea per comment
• include why it matters and a concrete suggestion
• avoid bikeshedding; keep tone constructive

4) Stage D: prioritize

Assign each comment a criticality:

• critical: must-fix
• optional: should-fix
• trivial: nice-to-fix

5) Stage E: show only critical + optional, then optionally post

1. Show the user only critical + optional comments.
2. Ask for explicit confirmation before posting:

"Post these to the PR now? (yes/no)"

1. If user says yes:

• Post inline comments for items with reliable path + line + side.
• Post one summary timeline comment that includes all critical + optional items.
• Do not post trivial items.

Posting comments with gh

Summary timeline comment (PR is an issue)

Use the Issues API to post one summary comment:

gh api -X POST "repos/{owner}/{repo}/issues/<PR_NUMBER>/comments" \
  -f body="<summary markdown>"

Endpoint reference: POST /repos/{owner}/{repo}/issues/{issue_number}/comments.

Inline (line-level) review comments

Use the Pull Request Review Comments API:

SHA="$(gh pr view <PR> --json headRefOid -q .headRefOid)"

gh api -X POST "repos/{owner}/{repo}/pulls/<PR_NUMBER>/comments" \
  -f body="<comment markdown>" \
  -f commit_id="$SHA" \
  -f path="path/to/file.py" \
  -F line=42 \
  -f side=RIGHT

Endpoint reference: POST /repos/{owner}/{repo}/pulls/{pull_number}/comments.

Mapping a unified diff to (path, line, side)

Inline comments require an exact file path, a line number, and a side.

Use this deterministic approach for unified diffs:

• Each hunk header looks like @@ -old_start,old_count +new_start,new_count @@.

• Initialize counters: old_line = old_start, new_line = new_start.

• Walk each subsequent hunk line:

  • If the line starts with ' ' (context): increment both old_line and new_line.
  • If the line starts with '+' (addition): increment new_line only.
  • If the line starts with '-' (deletion): increment old_line only.

• To comment on the new code, use side=RIGHT and set line=new_line.

• To comment on a deletion, use side=LEFT and set line=old_line.

If you cannot reliably determine line/side (for example, complex hunks or uncertainty), do not post an inline comment. Include the item only in the summary timeline comment.