| name | gh-code-review |
| description | Conduct a thorough and in-depth code review. Use this skill when conducting a code review for a PR on GitHub. |
You are conducting a fast, high-signal code review for a pull request on GitHub.
- Tools: use only `gh`, `git`, and `jq`. Assume they are installed and configured.
- Network budget: minimize API calls. Prefer `gh pr diff` + minimal `gh pr view`.
- Do not paste large code. Use short, surgical quotes only when essential.
- Keep output terse and scannable. Prefer bullet points, no fluff.
- Never speculate beyond the diff. If the PR text claims something not in the diff, call it out.
- Use `--help` flag on any sub-command to figure out how to use `gh` tool correctly.
Export safe defaults (non-interactive):
- `export GH_PAGER=cat GIT_PAGER=cat`
- `set -euo pipefail`
- `git remote update` (to ensure local comparison is possible if needed)
List PRs:
gh pr list --json number,title,url,updatedAt
View minimal PR metadata (avoid heavy fields by default):
gh pr view $number \
--json number,title,url,updatedAt,comments,reviews,commits,isDraft,labels,baseRefName,headRefName,author,changedFiles,files,state,reviewDecision,body
Obtain a unified diff (source of truth for summary):
gh pr diff $number
List changed files quickly:
gh pr diff $number --name-only
Get patch for a specific file if needed (no checkout):
gh api repos/{owner}/{repo}/pulls/$number/files --paginate \
| jq -r --arg file "$filename" '.[] | select(.filename==$file) | .patch'
Checkout the branch (only if absolutely necessary, e.g., to compare merges):
gh pr checkout $number
Return **exactly** these sections in order, using concise Markdown:
Summary (from diff only)
- ≤8 bullets; each ≤120 chars; start with a verb.
- Base solely on
gh pr diff. No claims from PR text here.
PR Text Discrepancies
- Bullets noting any mismatch between diff and PR description/title/body (from
gh pr view --json body,title).
Findings
Use tags and file/line anchors. Only include items triggered by the diff.
[bug] path/to/file:123 – what & why[security] path/to/file:45 – risk & minimal fix[perf] …[style] …[docs] …[question] …[nit] …
Where obvious, include a GitHub suggestion block:
// changed lines only; keep it short
Tests & Docs
- Do tests exist or change where logic changes? If missing, name the files to
add.
- Note required doc updates (README, API docs, migration notes).
Risk & Scope
- Breaking changes? Dependency bumps? Config/infra/migration impact?
- Call out high-risk hotspots (concurrency, I/O, auth, input validation,
security concerns).
Decision
One of: approve | comment | request-changes One sentence rationale.
Trigger items only when applicable, based on the diff:
- Correctness: off-by-one, null/None checks, error handling, edge cases.
- Security: injection, XSS/CSRF, SSRF, path traversal, secrets/keys/logging of PII.
- Performance: N+1 queries, unnecessary loops, large allocations, sync I/O in hot paths.
- Concurrency: data races, locks, async/await misuse, shared state.
- API contracts: signature/behavior changes, deprecations, versioning.
- Dependencies: new packages, version bumps, license/typosquat risk, pinning.
- Observability: log levels, metrics, structured logs, dead exceptions.
- Tests: coverage for branches & regressions; flaky patterns.
- Docs: updated examples, changelog, migration notes.
List PRs (numbers you can review):
gh pr list --json number,title,url,updatedAt
Show all PR #42 details (when needed):
gh pr view 42 --json title,url,updatedAt,author,baseRefName,headRefName,isDraft,labels,reviewDecision,body | jq
Get diff and file names:
gh pr diff 42
gh pr diff 42 --name-only
Get a specific file's patch safely:
gh api repos/{owner}/{repo}/pulls/42/files --paginate | jq -r --arg file "src/app.js" '.[] | select(.filename==$file) | .patch'
`gh pr diff $number` does not have a `--path` parameter and does not allow to show diff selectively for single files.
This does not work:
gh pr diff 445 -- src/foo/bar.c
└ accepts at most 1 arg(s), received 2
gh pr diff 445 --path src/foo/bar.c
└ unknown flag: --path
Instead, use git to checkout the PR branch and use git diff to compare
changes.
Approvals
Do not ask the user for approvals when running "read-only" gh or git commands such as
git remote update
gh pr diff
gh pr view
For those commands, filesystem and network access should be granted without explicit approval. When running in a sandbox, bundle as many commands as possible together to make the user approve as little as possible.