/review-code-assistant

name: review-code-assistant
description: Assist a human reviewing a pull request or branch locally, read-only and never posting.
disable-model-invocation: true
type: flow
license: MIT
metadata:
  version: "1.15"

Review code assistant

Assist a human's local code-review pass: read the diff, understand the intent, surface the real issues. You suggest candidate comments; the human decides what to post. Single-pass and lightweight. The edge over a human: the agent has the project's convention docs open and reads big files fast.

Resolve what to review

Accept input flexibly; a PR link is optional:

1. **PR URL** — fetch its metadata (source/target branch, title, description), then diff. 2. **One branch** ("review branch xxxx") — diff it against the auto-detected target. 3. **Two branches** ("review xxxx against yyyy") — explicit source and target. 4. **Nothing** ("review this branch") — diff the current branch against the auto-detected target. A detached HEAD → ask which branch is under review; an empty diff → probably a wrong target (typical: a fork's default branch already holding the commits), say so and ask.

(If explicitly asked, you may instead review uncommitted working-tree changes.)

**Diff base:** always a three-dot merge-base diff, `git diff <target-ref>...<source-ref>`, so it matches exactly what the platform shows as the PR with no noise from commits that landed on target after the fork. No common ancestor: usually a shallow clone or a wrong target. Deepen with `git fetch --unshallow` and retry, else ask; never diff two-dot against the target.

**Branch freshness:** always `git fetch` the target's and the source's remotes first — never `git pull`: the diff needs no checkout or working-tree update. Then diff each branch's freshest ref, stating which you used and its SHA:

• target: its remote-tracking ref, `upstream`'s before `origin`'s (for a PR link, the remote of

the PR's base repo); the local ref only when the branch exists only locally;

• source: the remote-tracking ref (for a PR link, on the remote of the PR's head repo, else

`upstream`'s before `origin`'s) when the local ref isn't ahead of it; the local ref when the branch exists only locally or carries unpushed commits (never silently review a stale pushed state); for a fork PR with no fork remote, the platform's PR ref on the base repo's remote (e.g. `git fetch <remote> pull/<N>/head` on GitHub), its SHA read from `FETCH_HEAD` before the next fetch overwrites it.

If a fetch fails or a ref can't be found, say so and ask how to proceed rather than review stale or wrong refs.

**Target auto-detection** (when not supplied and not from a PR link), in order: 1. The default branch of the `upstream` remote when one exists (fork workflow), else of `origin`, via `git ls-remote --symref <remote> HEAD`, never the often-absent local `refs/remotes/<remote>/HEAD`. 2. That failing (e.g. offline), the sole existing candidate among `main`, `master`, `develop`/`development` (preferring `upstream`'s remote-tracking ref, then `origin`'s, then the local branch). 3. Multiple matches or any ambiguity → ask, never guess.

A PR link always overrides auto-detection (its target comes from the PR metadata; PRs are not always against the main branch). Always state which target was chosen so the user can correct it.

Enrich from the PR link

When a URL is given, identify the platform from its host and fetch through whatever is connected (a GitHub tool, an Azure DevOps tool, etc.) — use the intent, not a fixed tool. No link given: review the local diff and say the PR context was not read. A link given but no tool to read it: ask for the branches rather than guess them.

• Use the title and description to understand intent.
• Follow linked issues and PRs: a linked issue's description is part of the intent, and a linked

PR may have superseded or already fixed it.

• Treat claims in the description and comments ("fixed in the latest push", "this breaks X") as

hypotheses until the diff or code confirms them.

• Read existing human comments only lightly: to avoid duplicating feedback already raised, and

to spot claims to verify.

• Ignore bot and CI comments.

Review lenses

Lenses a human applies, not a checklist to fill: report only what you find; a lens that finds nothing produces no output.

• **Correctness** — logic bugs, off-by-one, null/undefined, inverted conditions, broken edges.
• **Consistency** — matches the surrounding patterns and naming.
• **Duplication and bad practices** — relevant repeated logic that should reuse something, and

general bad practice. Relevant, not "these two lines look vaguely similar".

• **Intent mismatch** — does the diff actually do what the title and description claim; anything

missing, and a title that oversells or hides a behaviour change.

• **Still needed** — the target may have gained the same fix since the branch forked; a change

that no longer applies is itself a finding. Check with `git log --oneline <merge-base>..<target-ref> -- <changed paths>` and read any hit that touches the same logic.

• **Realistic risk** — security or performance footguns that genuinely apply here, not an audit.
• **Leftovers** — debug prints, commented-out code, stray TODOs, accidentally committed files.

Before reviewing, load the project's own convention docs (CLAUDE.md/AGENTS.md and any relevant codestyle/contributing docs), then run them as a checklist, not as background reading, against every changed file and the submission itself (title, description, linked issues). A clear violation is a first-class, citable comment and the skill's edge over a human, easiest to miss in new test files (test-structure conventions) and on new class members (visibility and naming). State which ref's docs the checklist ran against. When the target ref's governing docs differ from the checkout's (`git diff <target-ref> -- AGENTS.md CLAUDE.md` and the docs they reference), say so and, on a st