review-branch

Prompt file imported from alexander-shamray/blueprint-admin (.claude/commands/review-branch.md). Fill in {{arguments}} before use. Copyright stays with the author.

Review uncommitted or branch work for contradictions and self-consistency issues, and manage suggestions.md at the repository root. Every rule's argument is in docs/commands/review-branch.md. The same bar is the one the branch-reviewer agent reads in /ship step 5.

Mode selection (do this first)

Before choosing a mode, check whether suggestions.md exists at the repo root. That file is the running record of open issues; when it is present, the default job is to re-verify it, not to start a fresh review.

Prefer the file's presence over the empty argument list.

What counts as a finding

The bar is two statements that cannot both be true, or a statement that cannot be true of the system described — not pure style taste. Prefer:

1. Document ↔ code drift (samples, pins, type names, provider order, endpoints, ports, credentials). The design spec (docs/superpowers/specs/2026-09-14-blueprint-admin-design.md) and README.md make checkable claims; AdminOptions.cs owns ports and sibling paths.
2. Cross-document / CLAUDE.md contradictions — two rules that cannot both be true, or a planned tree stated as present. A stale restatement is a finding only if this branch introduces or edits it (docs/change-locality.md §2).
3. Pin drift — Directory.Packages.props vs a PackageReference; src/Admin.Web/package.json vs its lockfile; global.json vs the SDK the Host builds with.
4. CI drift — .github/workflows/ci.yml against docs/testing.md.
5. Incomplete reconciliation — a rule or fix this change states that the corpus still violates in the same change set.
6. A file outside the declared touch set: each outside <path> line of bash .claude/scripts/pr-locality.sh <n> (<n> from bash .claude/scripts/pr-for-branch.sh), resolved per docs/change-locality.md §3 — a narrower diff, a row widened with its reason, or a different class — never a row widened silently. Where the helper prints nothing or cannot run, say so and skip; never infer a class. An inside line grants nothing. (why: docs/commands/review-branch.md, What counts as a finding)

Reject as non-findings only the house styles this repository settled — British prose beside real identifier spellings, and the C# dialect .editorconfig enforces — and stale restatements docs/change-locality.md §2 leaves in place where the owner site is already correct. Do not reject frontend-only forms.

Recheck mode

Trigger: suggestions.md is present (default), or {{arguments}} contains recheck.

1. Read suggestions.md in full. Enumerate every numbered issue. If none, say so and offer a full review rather than inventing items.
2. For each issue, independently: locate the sites named under Where / File (grep siblings if the lines moved), verify the Problem against the current tree and tip, and set exactly one status: fixed, open, correct (only if the file or the user already said so) or false positive (never held, or no longer a defect).
3. Do not invent new issues, unless verifying a listed item surfaces a direct regression of that item. A full sweep is full, not recheck.
4. Rewrite suggestions.md: the status table and every Status line, fixed items kept briefly, Re-checked: bumped to today.
5. If every issue is fixed, correct, or false positive: delete suggestions.md and report one line of evidence per former issue.
6. If any issue remains open: keep the file, report counts.

Full review mode

Trigger: no suggestions.md, or full / full --local.

1. Establish the range. Branch: run git merge-base origin/main HEAD on its own (fall back to main) and carry the sha it prints into every later command — a shell variable does not outlive the call, and an empty one turns <merge-base>..HEAD into an empty range that reads as a clean review. Then git diff --stat / --name-only / full, and git log --oneline, over <merge-base>..HEAD. --local: git status --short and git diff HEAD.

2. Read the change, starting from its blast radius. Run codebase-index diff-impact --base <merge-base> --json first, or --base HEAD under --local; its list is where the search starts, not where it stops, since it names no absences. Prefer full source of load-bearing files over the diff; Grep src/, e2e/ and docs/ for every touched symbol and the one spec section that owns a rule the change moved. Never tour the corpus for a value.

3. Run cheap gates when the range touches them: bash .claude/scripts/host-checks.sh [all|fast] and bash .claude/scripts/npm-checks.sh [all|fast|lint|test|build] for src/ or toolchain files; bash .claude/scripts/harness-checks.sh for .claude/**, .github/locality-gate/** or tools/**. The Playwright suite is CI's smoke job: say it was not run, never imply it was.

4. Author findings only when verified. Quote the conflicting sites. Severity: bug | suggestion | nit.

5. Write suggestions.md at the repo root when any issue is open:

   # Suggestions — branch vs `main`   # or "local uncommitted"
   
   **Reviewed:** <ISO date>
   **Branch:** <name>
   **Base:** origin/main @ <short sha>
   **Scope:** <one line>
   **Diff:** <N files, +/- lines>
   
   ## Overall
   <2–4 sentences>
   
   | # | Severity | Item | Status |
   |---|---|---|---|
   | **1** | bug | … | open |
   
   ## Bugs / Suggestions / Nits
   ### 1. …
   
   | | |
   |---|---|
   | **Where** | … |
   | **Status** | open |
   
   **Problem.** …
   **Suggestion.** …
   
   ## What looks good (no action)
   …
   
   ## Recommended fix order
   …

6. If the review finds nothing open, create no file; under full, delete an old one when clean, replace it when not.

7. suggestions.md is working state. Never commit it or add it to the index; say so if the user is about to ship.

Report (chat)

Always end with: the mode actually run (and branch/base or local); whether suggestions.md was present at start; issue counts by status; its path if kept, or that it was deleted or not created; one line per top remaining finding.

Never fix findings in this command unless the user asks to apply them after the review. That is enforced by the frontmatter's disallowed-tools, which path-scopes Edit away from every tracked tree and root file and denies the toolchain's auto-loaded names; a redirection on a granted Bash command is a residual the hook bounds from the other side. (why: docs/commands/review-branch.md, The frontmatter denies, and what stays open)