ship-gate

name

ship-gate

description

The ritual for taking completed, verified work up for review. Use the moment a build is done and ready to go up: when finishing a chunk, opening or putting up a PR, or shipping a change. Open the PR first to start the external reviewer, then in parallel run a swarm of fresh independent Opus hunters over the diff, reconcile their findings with the external reviewer's into one classified list, dispatch the `steward` to own closeout (rebase, paginate/triage threads, resolve, re-verify, merge to the integration branch), routing REAL bugs to the `bug-fixer` for root-cause repair, and loop until CLEAN. Make sure to use this whenever work is finished and about to go up for review, so you find your own bugs instead of waiting on the PR queue.

Ship Gate

This is what "done" means for a chunk: not "the build runs," but "the build has survived a parallel adversarial swarm and the external reviewer, and every real finding is repaired at the root." You reach this gate only after the build is verified against the definition of done and the approved spec and plan. Drift from those is a defect even when the code runs; catch it here, not after merge.

The point of the gate is to stop waiting. The external reviewer runs on its own latency; your own hunters run on yours. Run them at the same time so you are never idle, and so you catch the bug class before the external pass does (front-running, per adversarial-review).

The sequence

1. Open the PR first. Putting it up starts the external reviewer's clock immediately, so it churns while you work. Do this before anything else at the gate. How the PR is opened and how the external reviewer is triggered are project mechanics; they live in the repo's CLAUDE.md.
2. Launch the internal swarm in parallel. Spawn a panel of fresh, independent hunter agents, one lens each, over the diff, per adversarial-review. Default to about five for a substantive PR; scale down for a trivial change and up for anything touching isolation, security, contracts, or data. Hunters work in their own worktrees and aren't branch-writers, so a swarm runs safely alongside the work. Each reads the diff line-by-line (running the touched tests to confirm, not just reasoning), cites file:line, labels findings REAL or SUSPECTED — and enumerates the whole class, not a few, so the fix can be holistic.
3. Reconcile the two streams. When the swarm returns and the external reviewer reports, merge both into one list. Dedupe: five hunters and an external pass will report the same defect in different words. Classify each finding REAL / DEFERRED / INVALID against the actual code. Don't blind-trust either stream; some external findings are stale or wrong, some internal ones are speculation. The output is one deduped, classified worklist, not five reports and a robot's comments sitting side by side.
4. Close out at the root, once. Hand the reconciled worklist to the steward, who owns closeout — rebase, thread triage, disposition, re-verify, and merge to the integration branch. The steward routes the REAL findings to the bug-fixer — the Opus root-cause specialist, not a plan-executor — because turning many overlapping findings into one holistic repair is independent-judgment work, not plan execution. The bug-fixer repairs them as a single integration pass, per integrate-dont-bolt-on, not as N separate patches: overlapping symptoms usually trace to one root cause, so fixing the cause once makes the symptoms fall together. Every fix is non-vacuous (test RED, fix, GREEN, then red-green-refactor) per adversarial-review. The reconciled worklist carries findings and the invariants they violate; any fix a hunter prescribes is advisory, and the bug-fixer re-derives it at the root and verifies the direction against the invariant rather than installing the prescription on faith. Thread-resolution rule (this is its canonical home): the steward resolves and closes every thread it dispositions — trivial/disposition items and DEFERRED items (each with a stated reason) directly, and for a routed REAL bug the bug-fixer replies citing the fixing commit while the steward resolves the thread. One resolve-owner (the steward); the bug-fixer supplies the fixing reply. (Outside a steward-owned closeout — a bug-fixer dispatched directly on a small PR with no steward — the bug-fixer both replies and resolves.) The steward's full closeout protocol lives in steward.md; this skill references it rather than restating it. A swarm plus an external reviewer is exactly the situation that tempts a bolt-on per finding and produces the long bug-round tail; resist it here. Write any reconciled worklist or closeout report with the Write/Edit tools, never with Bash heredocs (cat > f << EOF) — a heredoc silently truncates on a broken shell, landing a partial file that reports success.
5. Re-review to CLEAN. Re-run the loop over the new diff, including the code you just added, until a confirming pass returns zero real findings. A re-trigger of either the swarm or the external reviewer is an open loop until it comes back; track it, and never read absence-of-notification as success (per process-health-monitor).

Done, and who merges

The closeout re-verifies state live against the current head before declaring anything — never from a prior report's numbers. The principle: verify live, paginate review threads to exhaustion, confirm mergeable per-PR (not from a list endpoint), pin "clean" to the current head SHA, and never trust a cached count. A thread count that lands exactly on the page size is an early-stop in disguise; a mergeable read off the list endpoint is a cache-miss null waiting to be misread as "no conflicts"; and a "clean" verdict on a SHA the head has since moved past is stale. The gh/GraphQL commands that do this are project mechanics and stay out of this skill (per "Keep tooling out"); they live in the repo's CLAUDE.md.

A PR passes the gate when the hunter swarm is CLEAN on the current tip, every real external finding is fixed or explicitly deferred with a stated reason, the suite has actually run green (not reasoned-correct), and the build matches the spec, plan, and definition of done. Until then it's in-flight, not done.

Two kinds of PR, two merge rules:

• A groomed story → its epic's integration branch. Closeout — the rebase, the live re-verify, and the merge into the integration branch — is the steward's, dispatched as soon as the story clears the bar above (and the external reviewer has approved, if your setup runs it on non-default-base PRs). Stories flow without the user — that's the point.
• The integration branch → main. Once the epic is assembled there, this PR gets the full swarm + external-reviewer cycle, and the user merges it. Agents never merge to main.

If the external reviewer goes silent — no new review within 20 minutes of your last push — don't keep waiting: the hunter swarm becomes the gate, and you proceed on it (say so to the user). Each push restarts that clock, since a push is what re-triggers the reviewer; so the 20 minutes is always measured from the most recent push, not from when the PR opened. The same fallback applies if the reviewer is rate-limited or down.

Scale to the stakes

Five hunters and the full reconciliation are for substantive changes. A one-line config fix does not earn a swarm; put up the PR, let the external reviewer run, and a single lens is enough. Over-gating trivia stalls the forward motion as surely as under-gating risk breaks it.

Keep tooling out

The commands to open the PR, read the external reviewer's findings, and re-trigger it are project mechanics and live in the repo's CLAUDE.md. This skill is the ritual; the repo supplies the wiring.