Review PR

Review Pull Request

When to use this skill

Use this skill when you need to review a GitHub pull request in this repository — checking whether it fulfils the issue it addresses, whether the code itself is correct and well tested, and whether it respects the repository's architecture — and to publish that review as a single GitHub pull request review with a general comment and per-finding inline comments.

Inputs

Provide (all optional; a sensible default applies):

• pr_url or pr_number: a full GitHub pull request URL, or a bare number in this repository. If omitted, the skill looks up the open pull request for the current branch.

Procedure

1. Resolve the target PR. Accept a full PR URL, a bare number, or nothing.

   • A full URL fully identifies owner/repo/number.
   • A bare number is assumed to belong to this repository's origin remote (javierbrea/eslint-plugin-boundaries).
   • With no argument, find the current branch and look up the open pull request for it (prefer a GitHub MCP tool such as pull_request_read/list_pull_requests; fall back to gh pr view --json url,number). If none exists, tell the user and stop.
   • Fetch the PR's metadata, changed files and diff, and existing review comments (prefer pull_request_read).

2. Sync the local checkout. Compare the current branch and its HEAD commit against the PR's head ref and head commit sha.

   • If they already match, proceed directly.
   • If they differ, state exactly what differs (branch name and/or commit sha) and ask for explicit permission before doing anything: git fetch origin <headRef> then checkout. If the working tree has uncommitted changes, warn about that first and never discard local work without confirmation.
   • If the user declines the checkout, continue in GitHub-only mode: review using the PR's diff and file contents fetched over the GitHub API/MCP instead of the local working tree. Remember this for the final report — local checks such as running tests or lint cannot be performed in this mode.

3. Discover the related issue, to obtain the functional specification the change is meant to satisfy. Try in order:

   • A closes #<number> / fixes #<number> / resolves #<number> reference (or GitHub's own linked-issues field) in the PR body.
   • A number in the PR's source branch name (for example 477 in fix/477/migration-guide-links).
   • A (#<number>) token in the commits on the branch (this repository's commit convention is <type>(#<number>): <description>).
   • If an issue is found, read it in full — including its comments — with issue_read (or gh issue view <number> --json title,body,comments) to build the functional spec.
   • If no issue is found, proceed in issue-less mode: derive the spec from the PR title and description only.

4. Gather review context.

   • The diff of the PR against its base branch, and the full list of changed files.
   • The PR's existing review comments and conversation — do not raise a finding that has already been raised by someone else; note where you agree/disagree with an existing unresolved comment instead.
   • The base branch's relevant AGENTS.md file(s) for any package touched by the diff (see this repository's CLAUDE.md layering: read a project's own AGENTS.md before reviewing a change there).

5. Perspective 1 — functional review against the issue (perform this yourself, do not delegate). Using the spec built in step 3:

   • Does the change actually implement what the issue describes? Note missing cases, deviations, or behaviour the issue calls for that the diff does not deliver.
   • Are there functional problems beyond the issue's literal scope (regressions, edge cases, broken assumptions)?
   • Does the PR description accurately describe what the diff does?
   • Were tests added or updated for the new/changed behaviour?
   • Is there a CHANGELOG.md entry under "unreleased", and was the package version bumped consistently with SemVer, per .github/CONTRIBUTING.md and .agents/rules/changelog-and-versioning.md?
   • When the change is user-visible, was documentation updated accordingly — the package README.md, docs/**, and/or the website content under packages/website/docs/** (per .agents/rules/docs-authoring.md)? Flag it only when the issue or diff implies user-visible behaviour actually changed.

6. Perspective 2 — delegate to the reviewer subagent for code correctness, quality, and test coverage. Give it: the PR number and title, the base branch and diff range (<base>...<headSha>), the list of changed files, and whether the review is running in GitHub-only mode (so it knows whether it can run tests/lint locally).

7. Perspective 3 — delegate to the architecture-reviewer subagent for boundary/dependency-direction/Nx-graph compliance. Give it the same context as step 6, plus the functional spec derived in step 3, so it can judge not only compliance but whether the change is architecturally well-placed for what the issue actually requires, and flag a better structural alternative if one exists.

   Run steps 6 and 7 in parallel, in a single message — they are independent.

8. Consolidate the three perspectives.

   • Merge all findings; drop exact or near duplicates between perspectives.
   • Drop anything already raised in an existing unresolved PR comment (step 4).
   • Drop speculative or low-confidence findings — do not report a "maybe" as a finding.
   • For each surviving finding, record: file path, line (must fall within the diff — see Notes), severity (blocking / non-blocking / nit), a one- or two-sentence explanation, and — when the fix is small and localized — a GitHub suggestion block with the exact replacement code.
   • Draft the general/overall comment: a short assessment of overall code quality, structure, and whether the PR fulfils the issue, plus a summary of how many findings of each severity follow as inline comments. If there are no findings, the general comment says so plainly and is the entire review.

9. Show a mandatory preview. Present the full general comment and a numbered list of every inline comment (file:line, severity, explanation, suggestion if any). Ask for explicit confirmation before posting anything. Let the user drop, edit, or downgrade individual findings before proceeding. Do not post anything before this confirmation.

10. Post the review, using the GitHub MCP review flow:

    • pull_request_review_write with method: create to open a pending review, including the general comment as its body.
    • add_comment_to_pending_review once per confirmed inline finding, with the suggestion block included in the comment body when applicable.
    • pull_request_review_write with method: submit_pending and event: COMMENT to submit. The review is always submitted as a comment — never APPROVE, never REQUEST_CHANGES; the human maintainer decides the verdict.
    • Fall back to gh CLI or REST only for operations the MCP tools do not support.

11. No findings is a valid, complete outcome. If nothing survives step 8, submit the general comment alone. Do not invent problems to justify inline comments.

12. Report to the user: the review URL, the count of findings by severity that were posted, whether the review ran in GitHub-only mode, and whether an issue was found and used for the functional spec.