be-review - SKILL.md Agent Skill

name: be-review description: Run /be's review gauntlet SERIALLY — /lens-debate (lowy ⇄ hickey), then /codex-debate, then /simplify, then code-police, each editing and committing on the live branch in turn. Use from /be §4, or when the user asks to "run the review gauntlet". Requires Claude Code's Skill tool. argument-hint: "[--base ] [--rationale ] [--context ] [--tracks lens,codex,simplify,police]"

Review gauntlet (serial)

Run four reviewers one after another on the live branch, each the sole editor while it runs. Collisions are an edit problem: two reviewers writing the same worktree at once see torn, half-edited state. Running serially makes that impossible without any snapshot machinery — when a step starts, the previous step has already committed, so every reviewer reads a clean, settled tree and applies its own fixes directly:

/lens-debate — lowy + hickey debate boundaries/simplicity to consensus, then apply the agreed fixes (each its own commit). Pass the change rationale so the lenses don't flag deliberate decisions.
/codex-debate — codex (xhigh) ⇄ claude author, debating to consensus. Its author rounds edit and each round auto-commits fix(…) on the branch.
/simplify — the self-applying reuse / simplification / efficiency pass over the changed code. Now that nothing runs concurrently, it runs as itself (it could not against the old read-only snapshot).
code-police — its rule-checklist and fact-check passes, applying their fixes. Run with --no-elegance so its elegance pass is skipped: that pass re-invokes /simplify, which step 3 already ran over this same tree.

Each step runs to completion before the next begins. Wall-clock is lens + codex + simplify + police — slower than the old parallel form, but with no snapshot, no change-request handoff, and no separate apply pass: every step is its own editor and commits its own work.

PR comments come after the push, never before. Each step commits locally but be-review pushes only once, after all selected steps finish. A comment that names a commit SHA must never be posted while that SHA is local-only — if a later step failed or the run were interrupted, the PR would advertise commits that were never pushed. So the debate skills run with their self-commenting suppressed (--no-comment); be-review captures each comment body (the lens skill returns one ready; the codex body it assembles from commentHeader + the section files — step 2), pushes once at the end, and only then posts the lens comment, the codex comment, and its own police summary. No PR comment can reference a local-only commit.

Preflight

Non-empty diff. git diff --stat <base> (default: the repo default via git symbolic-ref --short refs/remotes/origin/HEAD). If empty, stop.
Commit first. Reviewers review committed code — commit/stash any outstanding work before starting (in /be this is automatic: §2/§3 commit and push before §4).
Resolve the scope once. git fetch origin, then MB=$(git merge-base <base> HEAD) and START=$(git rev-parse HEAD). Pass MB as the base to every step (their own merge-base resolution is idempotent on a SHA) so each reviews the change against the identical fork point. Note that each step sees the commits the previous step added as part of the diff — that is intended: a later reviewer reviews the earlier reviewer's fixes too. Run every git here with git -C "$repoPath" (below) so a cross-repo run resolves the target repo's base, not the cwd's.
Pin repoPath — the repo under review may NOT be the cwd. A /be run can carry the work in a companion repo (e.g. the drishti PR a @kolu/surface change requires per /be §5) while the session is rooted in a kolu worktree. Set repoPath to that target repo's absolute path (default: the cwd worktree root) and thread it into every step. The debate steps run as a Workflow, whose args MUST be a real object — Workflow({ scriptPath, args: { repoPath, base: MB, … } }). Passing args as a stringified JSON silently fails: the script does const a = args || {}; const repoPath = a.repoPath || '.', so a string a has no .repoPath, repoPath degrades to ., the debate runs git -C . against the (clean) cwd, and you get a vacuous false "clean" — a silently-skipped review gate, the worst gauntlet failure. If a cross-repo step returns clean with rounds: 0 against a non-empty target diff, suspect this before trusting it.
codex login (unless --tracks excludes it): codex login status. If not logged in, tell the user to run codex login (suggest the ! prefix) and continue with the remaining steps.

Run the steps in order

--tracks lens,codex,simplify,police selects which steps run (default all four), in the listed order. Run each to completion, then move to the next. Preflight already ran git fetch origin and resolved the base, so pass MB straight into each step and skip the per-skill step-1 fetch / base resolution — don't redo it once per step.

How to "wait for the Workflow" — let its own settle notification resume you. The debate skills run as a backgrounded Workflow ("launched in background; Task ID: …"); a debate can legitimately take 20–30 min. When it settles it fires its own task-notification that resumes this run automatically — that is the wait. So after dispatching a step, go to rest and let that notification wake you; do not schedule redundant ScheduleWakeup polls and there is nothing to babysit. (A prior run scheduled 4-min wakeups and the user wired a 5-min /loop to nudge a gauntlet that was simply mid-debate — both were unnecessary churn.) Only act when the workflow's notification arrives or it has provably errored.

lens — follow /lens-debate (Skill tool). repoPath = the live worktree, base = MB, apply mode (the default — do not pass --no-apply), --no-comment (so it doesn't advertise its local-only commits before be-review pushes — defer the comment until after the push), and thread the rationale through. It applies the agreed fixes as commits and returns its rendered comment body for be-review to post after the push. Wait for its Workflow to finish before starting the codex step.

/lens-debate returns a status of clean, consensus, apply-incomplete, unresolved, or merge-base-error:
- clean / consensus — the lenses agreed per-finding and applied the fixes.
- apply-incomplete — the lenses agreed, but the Apply phase didn't land every fix cleanly (see applyGaps: a fix was missing from the apply output or changed-but-uncommitted). Reconcile before moving on: for each gap, apply or commit the outstanding fix yourself (staging only its files), then fold the reconciliation into the deferred lens comment. Never report "lens consensus" for an apply-incomplete run.
- unresolved — the debate hit its round backstop with findings still contested. /be §4 requires you to adjudicate every unresolved lens finding yourself before moving on: surface them in the report, decide drop or apply for each, and apply the survivors before continuing. Fold your adjudication into the deferred lens comment you post after the push (the lens skill ran --no-comment, so there is no self-posted comment to follow up on). Never report "lens consensus" for an unresolved run.
- merge-base-error — the scope couldn't be trusted; report it and move on.
codex — follow /codex-debate (Skill tool). repoPath = the live worktree, base = MB, --no-comment (so it doesn't advertise its local-only round commits before be-review pushes), and thread both context (the task / main-agent context, so the codex author inherits what you know — not just the diff — every round) and rationale (so codex doesn't flag deliberate decisions at the source) straight through. Its step-2 Workflow runs in the background; wait for it to finish before starting the simplify step. It commits its rounds and returns a commentHeader plus the per-round section files under workDir (it no longer returns a single pre-rendered comment string). Assemble the comment body now and hold it to post after the final push — capture it immediately so a later step can't disturb the scratch:
```
{
  printf '%s\n' "$commentHeader"
  for f in "$workDir"/section-*.md; do printf '\n'; cat "$f"; printf '\n'; done
} > "$workDir/comment.md"   # hold this path for the post-after-push step
```
This freezes the body now, so any reconciliation a later branch performs (a commit-incomplete or section-incomplete fix-up below) is not in this file yet — append that note to $workDir/comment.md after you reconcile, or it won't reach the posted comment.

(On merge-base-error the workflow aborted before any debate ran, so there is no commentHeader/workDir/section-*.md to assemble — do not run the block above. Per /codex-debate, report the scope failure from the return's note, fix the base ref (e.g. git fetch), and re-run; there's nothing to post. On persistent reviewer-error there is likewise no body to post — an unresolved reviewer error is not a consensus to report; skip the codex comment in that case.)

Retry codex on reviewer-error (up to 3 attempts). /codex-debate ends in consensus, commit-incomplete / section-incomplete (see below), reviewer-error, or merge-base-error — reviewer-error meaning codex never produced a structured verdict even after codex-review.sh's built-in per-codex exec retries. That is an infrastructure hiccup, not a debate outcome: re-launch it immediately with the same args. Stop the moment an attempt reaches consensus. Only if all 3 come back reviewer-error do you give up on codex — report the persistent reviewer-error honestly (no false consensus comment) and move on to the simplify step.

On commit-incomplete, the debate converged but a round's author left its edits uncommitted (round numbers in commitGaps). The edits are still in the tree, but the per-round commit didn't land — commit the outstanding tree yourself (staging only the files that round changed, message fix: codex review — debate round N) before the simplify step, then append the reconciliation note to the already-frozen $workDir/comment.md (the body was captured above before this fix-up, so editing the section files wouldn't reach it). Don't report it as a clean consensus.

On section-incomplete, the debate converged but a round's author skipped or under-filled its disposition section file (missing, empty, or omitting a marker for an open finding; round numbers in sectionGaps), so the per-round trail — and thus $workDir/comment.md — has a gap for that round. The tree edits and commits are intact; the missing piece is the record. Append a note to the already-frozen $workDir/comment.md naming the round(s) whose disposition record is missing, and report it as converged-but-not-clean in your gauntlet summary. Don't report it as a clean consensus.
simplify — invoke /simplify (Skill tool), scoped to the change vs MB. It applies its fixes to the working tree. When it finishes, commit what it changed (refactor: simplify <area>, staging only the files it touched). If it changed nothing, note that and move on.
police — invoke /code-police (Skill tool), passing --no-elegance whenever the simplify track (step 3) ran this gauntlet. That flag skips Pass 3 (elegance), which would otherwise re-invoke /simplify over the tree step 3 already simplified — a full skill invocation to re-derive a near-guaranteed no-op. Pass 1 (rules) and Pass 2 (fact-check) still run. Only omit the flag when --tracks excluded simplify — then no standalone simplify ran, and the elegance pass is the run's one simplify, not redundant. Its embedded pass prompts diff against origin/HEAD...HEAD by default, which is wrong whenever --base isn't the repo default: before invoking, tell the police passes to scope to MB — pass the merge-base explicitly so every pass runs git diff <MB>...HEAD, not the default ref. Apply the fixes it surfaces, committing each fix(police): <title> with the finding in the message (stage only the files changed).

Push, then comment

First settle whether there is anything to push: git log --oneline $START..HEAD ($START was captured in Preflight). Then:

New commits exist and a PR exists for this branch (gh pr view --json number -q .number) → git push. Only after the push succeeds do you post the deferred comments — the lens and codex bodies from steps 1–2 are now safe to publish because the SHAs they name are on the remote.
No new commits (every step was clean or applied nothing) but a PR exists → there is nothing to push, and HEAD is already remote-visible, so post the deferred comments immediately. The local-only-SHA invariant is about never advertising an unpushed commit; with no new commit there is no such risk.
No PR → there is nothing to push to and nothing to comment on. Skip both; the local commits (if any) and their findings live in chat and the local log for the human.
A required push fails → do not post the comments (the SHAs are still local-only); report the push failure instead.

Never merge — pushing updates the open PR; the human reviews the commits and merges when satisfied.

When you do post, post one comment per track that produced a body — skip any track --tracks excluded, and skip a track that ran but yielded no postable comment (lens on merge-base-error, codex on persistent reviewer-error): the lens body and the codex body verbatim (gh pr comment -F — the codex body is the $workDir/comment.md you assembled in step 2 from commentHeader + the section files), and the police summary (the ## [👮 Code-police](https://agency.srid.ca/) comment described in Report).

Report

Summarize in chat — reporting only the selected tracks, and naming any track --tracks skipped so the absence is explicit, not silent:

lens — status (consensus + fixes applied, or unresolved + how many findings still need human adjudication and how you adjudicated each, or merge-base-error); its PR comment landed (posted after the push) — except on merge-base-error, which has no comment body to post.
codex — consensus / reviewer-error (note how many attempts if retried); on consensus its PR comment landed (posted after the push, per "Push, then comment") — on persistent reviewer-error there is no comment to post.
simplify — whether it changed anything and what it committed.
police — findings and how each was actioned; the ## [👮 Code-police](https://agency.srid.ca/) summary comment landed (posted after the push, alongside the lens and codex comments).
whether the fixes were pushed;
git log --oneline <base>..HEAD + git diff --stat <base> so the combined result is visible.

ARGUMENTS: