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?
   • Does the PR have the CHANGELOG.md entry required by .agents/rules/changelog-and-versioning.md, and, if it bumps a version, does the bump follow it?
   • 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.

Authorization Failure Handling (Required)

• Never enter retry loops with shell commands when authorization or authentication failures are detected.
• Treat errors such as 401, 403, Bad credentials, Requires authentication, Resource not accessible by integration, permission denied, or not authorized as terminal for the current automation attempt.
• On such failures, stop automation immediately and inform the user that authorization is required.
• Always include the full computed review — general comment plus every inline comment with its file:line and suggestion — in the response so the user can copy and paste it manually.
• Do not keep attempting alternative shell-based GitHub flows after an auth failure has been detected.

Output format

Return results with:

• Summary: the pull request reviewed, the review URL once posted, the number of findings by severity, whether GitHub-only mode was used, and whether a linked issue was found and used for functional context.
• Details: the general comment text and the full list of inline findings (file, line, severity, explanation, suggestion).
• On authorization failure: the copyable general comment and every inline comment, and a clear statement that authorization is required.

Include assumptions, risks, and follow-ups when relevant.

Examples

Example A (PR URL, linked issue, clean checkout)

Input

• Goal: review https://github.com/javierbrea/eslint-plugin-boundaries/pull/478.
• Context: the local branch is already checked out at the PR's head commit; the PR body contains closes #470.

Expected output

• Issue #470 read for functional context; reviewer and architecture-reviewer run in parallel; findings consolidated; preview shown and confirmed; a COMMENT review posted with a general comment and, say, two non-blocking inline comments; the review URL reported.

Example B (bare number, branch mismatch, checkout declined)

Input

• Goal: review PR 481 while on an unrelated local branch with uncommitted changes.
• Context: the user declines the offered checkout.

Expected output

• GitHub-only mode: diff and files fetched via the API/MCP instead of the working tree; the final report notes that local tests/lint could not be run; review still posted after preview confirmation.

Example C (current branch, no linked issue, no findings)

Input

• Goal: review the PR for the current branch; no argument given.
• Context: no issue reference in the PR body, branch name, or commits; the diff is small and clean.

Expected output

• Issue-less mode, spec drawn from the PR description only; both subagents report no significant issues; preview shows a general comment only, no inline comments; posted as COMMENT after confirmation.

Notes / Constraints

• Write every text with the writing-style skill.
• Inline comments may only anchor to a line present in the diff; a finding about code the diff does not touch belongs in the general comment instead.
• The review is always submitted with event: COMMENT. Never submit APPROVE or REQUEST_CHANGES automatically.
• Always show a preview and obtain explicit confirmation before posting the review.
• Never check out the PR branch, or discard local changes, without explicit permission.
• Prefer GitHub MCP tools for all supported operations; fall back to gh CLI or REST only for what MCP cannot do.
• If no problems are found, do not manufacture any — a general-comment-only review is a complete, valid result.