/gitnexus-review

name: gitnexus-review
description: 'Review code changes with GitNexus from a GitHub PR URL or number, a branch/ref or commit range, or local staged, unstaged, and untracked changes. Use when the user asks for a code review, merge-risk assessment, regression hunt, missing-test analysis, or a verdict on whether a PR, branch, commit range, or local diff is safe.'

GitNexus review

Review the requested change surface without editing source, committing, pushing, posting, or resolving threads. A later explicit request may authorize those actions. Use GitNexus for structural evidence and source inspection for proof; neither substitutes for the other.

Resolve the target

Accept these forms:

| Input | Review surface | | ------------------------------------------------------ | --------------------------------------------------------------------------- | | PR URL, `owner/repo#42`, `#42`, or bare number | GitHub PR | | `base...head` | Merge-base range | | `base..head` | Exact two-dot range | | Branch, tag, or commit | Ref against the repository default branch | | `local`, `staged`, `unstaged`, or working-tree wording | Local changes | | No target | Current branch's open PR; otherwise local changes; otherwise current branch |

An explicit target always wins. Interpret a bare number as a PR only in a GitHub repository with working `gh` authentication; otherwise ask for a ref or URL. If implicit mode finds both branch commits and local changes, review them as two labeled surfaces rather than silently dropping or blending either one.

Record the resolved target kind, repository root, default branch, base SHA, head SHA, merge-base when applicable, and included local states. Resolve the default branch from remote metadata (`refs/remotes/<remote>/HEAD` or GitHub repository metadata); use `main` or `master` only as an explicit fallback and say when doing so.

PR

Use `gh pr view`/`gh api` to pin the PR number, repository, title, URL, base ref, base SHA, head ref, and head SHA. Fetch those exact commits without switching the user's branch. Compute `git merge-base <base> <head>` and use that SHA as the review base: GitHub PR diffs are merge-base diffs, while `detect_changes(scope: "compare")` is a two-dot comparison.

Use the local `git diff <merge-base> <head>` as the complete diff source of truth; use GitHub metadata for PR facts and review state. For fork PRs, fetch the pull ref or the contributor remote instead of assuming the head branch exists on `origin`.

Branch, ref, or range

Resolve every ref to a commit before reviewing. For a branch or `A...B`, use the merge-base as the comparison base. For an explicit `A..B`, honor `A` as the exact base. Do not compare a feature branch directly with a moving default branch tip when merge-base semantics were intended.

Local changes

Inspect `git status --short`, the staged diff, the unstaged diff, and every untracked file. Use `detect_changes` with `staged`, `unstaged`, or `all` as requested. Untracked files are not guaranteed to appear in Git diff or graph mapping, so read them directly and list them in the review provenance.

Align the checkout and index

The graph and diff must describe the same head. Reuse an existing worktree only when it is at the exact target SHA. Otherwise create a temporary detached worktree for the PR/ref head, review there, and remove only that temporary worktree afterward. Never switch or reset the user's current worktree.

Check GitNexus status in the target worktree. If stale, run `node .gitnexus/run.cjs analyze --index-only` before trusting graph results (temporary worktrees never carry the gitignored `run.cjs` — fall back to the installed `gitnexus` CLI, then `npx gitnexus`), and include `--pdg` in that same refresh when the diff plausibly touches trust or data-flow boundaries, so the taint pass below doesn't pay a second full analyze. Taint and dependence evidence needs that PDG layer: when the workflow's taint pass finds it missing, rebuild with `analyze --pdg --index-only` and record the rebuild in provenance. For local changes, refresh the index so new or modified source is represented. If an exact target checkout/index cannot be established, state the limitation and do not claim a complete graph-backed review.

Review workflow

1. Read the full diff and changed-file list. Separate generated files, dependency churn, tests, and behavior changes. 2. Run `detect_changes` against the exact surface:

• PR/branch/`...`: `scope: "compare"`, `base_ref: <merge-base SHA>`.
• Explicit `A..B`: `scope: "compare"`, `base_ref: <A SHA>` from a worktree

at `B`.

• Local: `scope: "staged"`, `"unstaged"`, or `"all"`.

Pass `worktree` when the MCP server is attached elsewhere. 3. Run upstream `impact` with `includeTests: true` for each behaviorally changed symbol. Prioritize public contracts, shared types, control flow, persistence, security boundaries, and error handling; skip mechanical/generated changes. 4. Inspect every direct (`d=1`) dependent that is outside the diff. A dependent outside the diff is a lead, not automatically a bug—verify the changed contract and caller behavior in source. 5. Use `context` on key or ambiguous symbols and inspect affected execution flows. Read the surrounding implementation and tests at cited locations. 6. **Taint and dependence pass.** For changed code on trust or data-flow boundaries — externa