code-review

When to use

• User pastes a diff, patch, or PR URL and asks "review this", "is this safe to merge", "look for issues".
• User asks to self-review staged changes before committing (git diff --staged).
• User wants a security- or performance-focused pass on a specific file.
• User mentions N+1, SQL injection, XSS, authorization, race conditions, or unbounded loops.

Do not use this skill for architectural review of a design doc (use api-design or an ADR skill) or for large multi-PR audits (run this skill per PR).

Inputs

• A unified diff, a PR URL (resolved via the GitHub MCP), or a list of files to review.
• Optional: the language/framework (inferred if omitted), the repo's style guide or linter config, and the PR description so intent can be compared against implementation.

Outputs

A Markdown review with three sections:

1. Summary: 2-4 sentence assessment plus an overall verdict (approve, approve-with-nits, request-changes, block).
2. Findings table: one row per issue with columns Severity | File:Line | Category | Issue | Suggested fix.
3. Inline suggestions: for each high or blocker finding, a fenced code block showing the exact replacement.

Severity ladder: blocker (must fix, ship-stopping), high (fix before merge), medium (fix soon, track in issue), low (nit, optional), info (observation, no action).

Tool dependencies

• Read, Grep, Glob for local files.
• GitHub MCP (get_pull_request, get_pull_request_diff, get_pull_request_files) when reviewing a PR by URL.
• Optional: language-specific linters (eslint, ruff, golangci-lint, clippy) — run them if available and cite their output.

Procedure

1. Fetch the diff. If given a PR URL, use the GitHub MCP to pull the title, body, and unified diff. If given a branch, run git diff <base>...HEAD. Always obtain the full diff, not a summary — reviews over summarised diffs miss subtle bugs.
2. Read the PR description and identify the stated intent. Note any mismatch between intent and the actual changes; call that out in the summary.
3. Enumerate touched files and, for each non-trivial file, read at least 50 lines above and below the hunk to understand context. Never review a hunk in isolation.
4. Walk the checklist in references/review-checklist.md in order: security, correctness, performance, maintainability, testing, observability. Skipping a category is not acceptable; if a category does not apply, state so explicitly in the summary.
5. For each issue, assign a severity from the ladder above and write the finding using this template: <what is wrong> -> <why it matters> -> <concrete fix>. Always cite path/to/file.ext:Lstart-Lend.
6. Cross-check every flagged issue against references/common-antipatterns.md to ensure the label is precise (e.g. distinguish feature envy from law-of-demeter violations).
7. If the diff touches tests, confirm the tests actually exercise the new behaviour. A passing test that never asserts the new code path is a high finding.
8. If any finding is blocker or high, set the verdict to request-changes or block. Never mark a PR approve while high issues remain.
9. Emit the review in the output format above. Keep each finding under four lines; push rationale into links to the references.