Review Local Branch

Review the local branch (review-local-branch)

The sibling of review-pr, for work that has not become a PR yet. Same agents, same proof-of-work contract, same calibrations — the only real differences are how scope is discovered and that the code is yours.

Drafts only. This skill never commits, never pushes, never edits your working tree.

Trust model — what the sandbox is and is not here

review-pr puts an untrusted PR in a container because the code is a stranger's. Here the code is yours, already on your disk, and there is nothing to isolate it from. Be honest about that rather than implying a boundary that does not exist:

• sandbox start --local registers your checkout with no isolation. sandbox doctor will say so.
• What it still buys is uniformity: the agents speak only the CLI, so the same definitions work in both skills with no transport branch and no fallback path to fall down.
• What it also buys is a guardrail on your branch. A local sandbox is exec=screened: commands that obviously write — git checkout, rm, pnpm install, > redirects — are rejected, so a review cannot mutate the thing it was asked to review. It is a guardrail, not a security boundary.
• sandbox worktree still works. It cuts a peer worktree outside the repo, under ~/.nx-sandboxes/worktrees/<id>-<agent>, so an agent proving a test can fail never touches your files or your branch — the only thing it writes into your repo is the .git/worktrees registration, which sandbox stop removes.
• That worktree carries your uncommitted work, not just the last commit. git worktree add … HEAD would check out the committed state, which is not what is under review here; the CLI applies git diff HEAD on top so the tree matches the diff the agents were given. Untracked files stay out, exactly as they do from the diff.
• It is installed on creation, which on this repo is minutes rather than seconds. That cost is why agents are told to reach for one only when static reading genuinely cannot settle the question — not as a matter of course.

If you want an agent to run the repo's own build or test commands, start with --allow-exec and say so in the charter. No screen can contain those anyway — node -e is arbitrary code by construction.

Step 1: Establish scope

ROOT=$(git rev-parse --show-toplevel)
BRANCH=$(git rev-parse --abbrev-ref HEAD)
SLUG=$(printf '%s' "$BRANCH" | sed 's#[/ ]#-#g')

# Refresh the base so "is this net-new?" is answered against the real master,
# not a fork point that is weeks stale.
git fetch -q origin master

BASE=${ARG_BASE:-$(git merge-base origin/master HEAD)}
test -n "$BASE" || { echo "FATAL: no merge base with origin/master"; exit 1; }

--base <rev> overrides. Use it when the branch is stacked on another branch rather than on master — a merge-base against origin/master would then pull the parent branch's work into scope and the review would spend itself on code you did not write.

Refuse to run on the default branch. If $BRANCH is master, there is no branch to review: merge-base origin/master HEAD is HEAD, the diff is empty, and every agent gets an empty scope. Say so and stop.

# Everything you would push: commits + staged + unstaged, in one surface.
git diff "$BASE" > /tmp/branch-$SLUG.diff.tmp \
  || { echo "FATAL: git diff failed"; exit 1; }
test -s /tmp/branch-$SLUG.diff.tmp \
  || { echo "FATAL: empty diff — nothing to review against $BASE"; exit 1; }
mv /tmp/branch-$SLUG.diff.tmp /tmp/branch-$SLUG.diff

git diff --name-only "$BASE" > /tmp/branch-$SLUG.files

# `|| true` is required, not defensive: grep exits 1 when nothing matches, so on a
# clean tree this pipeline fails, and under `set -e` in bash it aborts the block
# before the sandbox is ever started. Verified — zsh does not abort here and bash
# does, so the failure only shows up in some shells.
{ git status --porcelain | grep '^??' | sed 's/^?? //' || true; } > /tmp/branch-$SLUG.untracked

Write-then-verify-then-move, for the same reason review-pr does it: a bare > truncates the target before git runs, so a failure leaves a 0-byte file that every agent is then told is the complete diff.

git diff $BASE is deliberately two-dot-with-working-tree. It compares the base commit against your working tree, which is what "everything I would push" means — commits, staged, and unstaged together. Do not "fix" it to $BASE...HEAD: that drops staged and unstaged work, which on a branch mid-edit is usually the part most worth reviewing.

Untracked files cannot appear in a diff. A new file that was never git added is invisible to git diff at any syntax, and mutating the index to make it visible is not this skill's business. So they are collected separately and reported:

• If /tmp/branch-$SLUG.untracked is non-empty, list those paths in the draft under ## Not reviewed and say plainly that no agent saw them. A new file is exactly where a whole unreviewed feature hides, so this warning is load-bearing rather than a formality.
• Ignore the usual noise (node_modules, dist, .nx) — they are gitignored and will not appear here anyway.

Step 2: Start the sandbox

SANDBOX=$(tools/review-sandbox/sandbox start --local "$ROOT" --base "$BASE" | head -1)

# Read-only view for the lanes that must not run anything.
READONLY_SANDBOX=$(tools/review-sandbox/sandbox view "$SANDBOX" --exec none | head -1)

--base "$BASE" is what makes sandbox read <id> <path> --ref base work: it resolves to git show $BASE:<path> in your own checkout, so "was this already true before my branch?" is answerable with no second worktree and no second clone.

Step 3: Write the charter

Same shape as review-pr Step 5, minus everything the agents already carry. Write it to /tmp/branch-$SLUG.review-charter.md:

# Review charter

## Toolchain

This is the maintainer's own checkout, already installed. Do not install anything.

If a check must mutate source, run `sandbox worktree <SANDBOX> <your-agent-name> head`. It cuts a
peer worktree outside the repo that already carries the uncommitted work under review, so you may
mutate it freely. Never edit the checkout itself — it is the maintainer's live branch.

## What is under review

Branch `<BRANCH>`, diffed against `<BASE>` (<SHORT_SHA>, <SUBJECT>). The diff covers committed,
staged and unstaged changes together — this is everything that would be pushed.

<IF untracked files exist:> <N> untracked files are NOT in the diff and are NOT under review:
<list them>. Do not report findings about them; do not assume they are absent from the design.

## The problem being solved

<OMIT unless the user stated one, or a linked ticket/issue is known. Do not invent one from the
diff — a review that infers intent from the change cannot then judge the change against it.>

## Orientation — where this change sits

<Same rules as review-pr: call sites and base behavior in, rationale and conclusions out. Keep it to
~15 lines. Use `sandbox grep <SANDBOX> <symbol> packages` for call sites and
`sandbox read <SANDBOX> <path> --ref base` for base behavior.>

## What to report

Report **critical** and **important** findings, plus **strengths**. Concrete, actionable
nice-to-haves may go in a terse **Suggestions** list. When you endorse a debatable design decision,
say so in a **Maintainer calls** line rather than folding it into an endorsement.

A defect that reproduces unchanged at `--ref base` does not block this branch, but report it under
**Pre-existing** — one line per defect, no cap, naming the base line that proves it predates the
work. That list is what follow-up tickets get filed from; dropping it loses work nobody else is
positioned to redo.

Your own definition carries the calibrations that bind your dimension, and the proof-of-work
contract. Both still apply.

This is pre-PR review, so the bar moves one notch toward candor. In review-pr a rework request costs a contributor a round-trip, which is why its agents are told to endorse when torn. Here the author is the person reading the draft, and nothing has been published yet — a BETTER_ALTERNATIVE_EXISTS costs a rebase, not someone's afternoon. Say this in the charter so alternative-approach calibrates to it.