/review-code-assistant

name: review-code-assistant
description: Assist a human reviewing a pull request or branch locally — diff a source branch against its target (auto-detected or from a PR link) and return concise, human-voice review comments with file and line locations. Read-only, never posts.
disable-model-invocation: true
type: flow
license: MIT
metadata:
  version: "1.11"

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. Output is local text only.

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.

(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. Fall back to two-dot only when there is no common ancestor. No checkout is needed to produce the diff.

**Branch freshness:** always `git fetch` first — never `git pull`: the diff needs no checkout or working-tree update. Then diff each branch's freshest ref, stating which you used: the remote-tracking ref when the branch is on a remote and 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's source, absent from `origin`, the fork remote or the platform's PR ref (e.g. `git fetch origin pull/<N>/head` on GitHub). 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. `git symbolic-ref refs/remotes/origin/HEAD` — the remote default branch. 2. Else check which usual candidates exist (`main`, `master`, `develop`/`development`); exactly one match wins. 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. If no matching tool is available, or no link was given, degrade gracefully to a local-diff-only review, or ask.

• 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.

• **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).

Grounded, not speculative

The core rule. A comment may exist only when it points to concrete evidence of one of:

1. **The code is demonstrably wrong** — you can name the actual failure (this input throws, this condition is inverted, this loses the value). 2. **It breaks a documented project rule** — you can cite the convention (a doc, or an established pattern visible in the surrounding code). 3. **It is a concrete, behavior-preserving simplification** — needless indirection or duplication you can collapse with certainty, naming the exact redundancy and the smaller form. (E.g. a non-exported const in the class's own file that only aliases one class field is collapsible, or the same expression repeated across a template, collapsed into one named derivation; an exported or separate-file const is fine, it may be reused elsewhere.)

If you cannot name the evidence — the exact bug, rule, or redundancy — do not comment. Hedge phrases that signal a guess with no evidence ("there might be", "this co