/review-handoff

description: Generate a self-contained hand-off brief so ANOTHER agent (a fresh session, Codex, any external reviewer) can pick up the exact state and review it - a plan, a branch, the last commits, a PR, or one file. Produces one pasteable brief; reviews nothing itself.
argument-hint: "[PR-url-or-number|--pr <id>|--local|--staged|--last-commit|--branch|--plan [<path>]|--file <path>|--commits <N>|--range <a>..<b>] [--spec <path>|none]"

Review Handoff - Brief for an External Reviewer

Produce ONE message the user copies into another agent. That agent has NO context: not this conversation, not the task, not even which repo. The brief must be complete on its own.

• The brief is the deliverable - do not review anything yourself, do not edit any file
• Target selectors mirror `/lets:review`, so the same flag reviews here or hands off there; works in any git repo, with or without LETS

> **IMPORTANT:** If the spec below invokes any deferred tool (e.g. `AskUserQuestion`), you MUST load and call it as specified. Never skip the call, never substitute a default answer of your own — the tool invocation is part of the contract. This is critical.

Usage

/lets:review-handoff                      # infer the target from context; asks only if genuinely ambiguous
/lets:review-handoff <PR-url-or-number>   # GitHub or Bitbucket PR
/lets:review-handoff --pr <id-or-url>     # alias of the bare form above
/lets:review-handoff --local              # uncommitted changes
/lets:review-handoff --staged             # staged changes only
/lets:review-handoff --last-commit        # last commit
/lets:review-handoff --branch             # full branch vs the merge branch (three-dot, like a PR)
/lets:review-handoff --plan               # newest plan in .lets/plans/
/lets:review-handoff --plan <path>        # a specific plan file
/lets:review-handoff --file <path>        # one file
/lets:review-handoff --commits <N>        # handoff-only: the last N commits (a fix round)
/lets:review-handoff --range <a>..<b>     # handoff-only: an explicit range
/lets:review-handoff --spec <path>        # what the reviewer judges against (or a bare task id)
/lets:review-handoff --spec none          # deliberately no spec - no spec line, no caveat

Selectors match `/lets:review`, with two deliberate differences: `--commits` / `--range` are **handoff-only** (review has no target for "the commits that answer a review round"), and `--pr` is kept as an alias because it is the spelling this tool shipped with. Review's output modifiers `--json` and `--workflow` are **not** implemented here.

Step 1: Determine the target

• PR URL/number, or `--pr <id-or-url>` -> **PR mode**. `--local` / `--staged` / `--last-commit` / `--branch` / `--commits N` / `--range a..b` -> **local mode**. `--plan [path]` -> **plan mode**. `--file <path>` -> **file mode**.
• **Host resolution.** A `github.com` URL -> `gh`; a `bitbucket.org` URL -> `bbb`, whose PR number sits in the `/pull-requests/<n>` segment, not github's `/pull/<n>`; a bare number -> `{LETS_PR_FLOW}`. **When `{LETS_PR_FLOW}` is empty** - the normal state outside a LETS project, where the hook emits only four keys - fall through to the forge named by the `origin` URL Step 2 prints. Only when neither names a github or bitbucket host: stop and say a PR hand-off needs one.
• **No argument -> infer, do not ask by default.** Take the target from the user's sentence next to the command ("цих правок" -> the just-committed fixes; "цієї гілки" -> `--branch`; "план" -> `--plan`; "коміта" -> `--last-commit`) and from what just happened in the session. Only when genuinely ambiguous, ask **one** `AskUserQuestion` (header `Target`, `multiSelect: false`) offering Local changes / Branch / Plan / Last commit. Otherwise decide, and name the choice in the closing line.
• The flag-only targets (`--staged`, `--commits`, `--range`, `--file`) are not in the interactive menu.

Step 2: Locate

ROOT=$(git rev-parse --show-toplevel); GIT_DIR=$(git rev-parse --git-dir)
echo "root=$ROOT branch=$(git branch --show-current)"
echo "head=$(git rev-parse HEAD) $(git log -1 --format=%s)"
git remote -v | head -2
case "$GIT_DIR" in *worktrees/*) echo "worktree=yes main_repo=$(git rev-parse --path-format=absolute --git-common-dir | sed 's#/.git$##')";; *) echo "worktree=no";; esac
git status --short | head -20; echo "dirty_files=$(git status --short | wc -l | tr -d ' ')"
# The hook resolves this per-repo, correctly, including in a repo with no LETS. Do NOT add a
# fallback resolver here: it would mask a config-layer defect for every other consumer of the key.
MB="{LETS_MERGE_BRANCH}"
BASE=$(git merge-base HEAD "origin/$MB" 2>/dev/null || git merge-base HEAD "$MB" 2>/dev/null)
echo "merge_branch=$MB base=$BASE ahead=$(git rev-list --count "$BASE"..HEAD 2>/dev/null)"
git log --oneline "$BASE"..HEAD 2>/dev/null | head -30

`{LETS_MERGE_BRANCH}` is substituted by the orchestrator before the block runs - never `$LETS_MERGE_BRANCH`, which yields empty in a bash block. When `BASE` comes back empty, say so in the brief and name the branch that was tried, rather than emitting a base the reviewer cannot act on. Also carry into the brief: whether `.lets/` exists, and a nested-repo layout (a repo under `code/<name>/` of a parent workspace - name BOTH paths).

Step 3: Target facts

**Run the commands, never recall from memory** - the same rule as Step 2, and it binds hardest here, because this is where a session that already did the work is most tempted to narrate it. A commit's intent comes from its message; whether a file is new or modified, and how many lines moved, comes from `git show --stat` / `git diff --stat`. A brief that calls an appended-to file "new" costs the reviewer their trust in every other line of it.

| Mode | Gather | |---|---| | `--plan` | absolute path, title line, task count, `[DONE]` markers, which code it will touch, whether execution started (commits since the plan's date). An uns