| name | brief-review |
| description | Adversarially review a graveyard shift's brief BEFORE it's published — kill false gates, sharpen real ones, surface actionable work the shift left behind, and loop the graveyard if real work remains. Use as the closing/looping phase of graveyard-shift, right after the Shift Report is drafted and before it's published to Notion. This is what makes a graveyard shift loop until review finds no actionable-now work remaining; it is NOT run during a shift-change (that's a live meeting with the user and can't loop). |
Brief Review
A graveyard shift's brief is not done when it's written — it's done when it survives review. Writing the brief creates "I'm done" gravity, and that gravity is exactly what lets false gates and leftover work slip through into the report the user reads. This phase runs one "am I under-acting anywhere?" pass over the finished brief, then decides whether to loop the shift.
Where it sits
The closing/looping phase of graveyard-shift: after the shift's work has landed on GitHub and the Shift Report is drafted, but before it's published to Notion. It is the mechanism that makes a graveyard shift loop — review the brief, and if real work remains, go around again ("doing a graveyard shift as part of the graveyard shift").
Its output — the reviewed brief — is the baseline a later shift-change conversation consumes. Do not run brief-review during a shift-change. A shift-change is a live meeting with the user; it can't loop, and the decisions it walks should already be false-gate-stripped by this phase. (If false gates reach the user, it's because the review happened live in the meeting instead of here, adversarially, before handoff.)
The reviewer: fresh, adversarial, cross-model
Do not self-review — the mind that wrote the brief will rubber-stamp it. Ship the brief across the street to a reviewer that (a) did not write it and (b) runs on a different top-tier model than did the primary work. The cross-family separation is what defeats the "done" gravity.
Provider order — go to the BEST cross-model reviewer, not a convenient same-family fallback. The two top providers are Codex and Claude; the primary move is the swap between them:
- Orchestrated in Claude → review with Codex. Orchestrated in Codex → review with Claude. This is first choice, always.
- Backups, only if the primary is genuinely unavailable (no quota, no auth): Gemini/
agy, then Cursor, then antigravity/Inti.
- Hard rule: never fall back to a same-family reviewer just because a backup tool broke. A broken backup (e.g. the
agy/Gemini wrapper misbehaving) does NOT mean "cross-model is unavailable" — it means skip that backup and go to the primary cross-model provider (Codex). Falling to same-family Claude because a Gemini wrapper broke is the exact miss to avoid (it happened on the first outing): a same-family reviewer shares the author's blind spots, so the whole differentiator is lost. If — and only if — every cross-model provider is truly unreachable, run a fresh same-family reviewer AND flag in the brief that the review ran at reduced strength.
Record the provenance — the cross-model rule has teeth only if it's auditable. The reviewed brief MUST carry a one-line review-provenance stamp: reviewer used (e.g. "Codex"), the primary that was skipped and why (if any — "primary was Codex, used it" or "Codex unauthenticated → next cross-model"), backup attempted (if the primary was down), and whether the review ran at reduced strength (only true if every cross-model provider was unreachable and a same-family reviewer stood in). Without this stamp, "never same-family fallback" is an aspiration no one can check; with it, a later reader can see the rule was actually honored.
Charter the reviewer to decide READINESS, not to polish. This is not a copy-edit pass before handing to the user — it decides whether the brief is ready to give at all, which is a deeper, harder check. If the reviewer isn't pushing back, it isn't doing its job. Charter it explicitly:
"Assume this brief is NOT ready to give the user until you prove otherwise. Assume it is over-gated, under-executed, and over-claimed. For every recommendation, argue the opposite and see if it holds. Re-derive at least one load-bearing empirical claim from scratch (don't trust the numbers because they're 'internally consistent'). Challenge the framing and the spin, not just the metadata — is a negative being softened, a win being oversold, a real decision being hidden as 'awareness'? Kill every false gate; surface every real one. Find every actionable thing the shift left on the table. Verdict: is this ready, or not — and if not, exactly what has to change."
Lens 1 — decisions / gates (kill false gates, sharpen real ones)
This lens applies gate-check to the finished brief; it does not re-derive gate-check doctrine. Run each surfaced "waiting on you" item through the kill below — that is the whole of Lens 1's job. (Decision-section polish — wording, ordering — is not what this phase loops on; only Lens 2 work triggers another lap.)
Run every "waiting on you" item through gate-check's kill. Strike an item if any of these fire:
- Confident dominant rec — if a defensible default exists, it's bucket-1: do it, record the reasoning, drop it from the list.
- "Not blocking" — if you wrote that (or it's true), it isn't a gate. Strike.
- The contradiction tell — a recommendation and a request-for-decision in the same item = theater. You've already decided. Strike, or convert to "done — here's what I did."
For items that survive (genuinely the user's — irreversible / outward-facing / strategic fork with no dominant option): make them specific + current. A money/irreversible gate reads "$X unblocks operation Y, blocked now" — never "might want a top-up someday." If you can't name the number and the currently-blocked operation, it's not a gate; resolve it or drop it.
Lens 2 — work remaining (find what you left on the table)
Scan for actionable-now, independent work the shift didn't do. Exclude only: human-gated items, someday-tier, and work blocked on something in-flight. If real work survives that filter, the shift isn't drained.
The trap: "shaped" is not "done." A graveyard is supposed to loop shape→build in the same shift — shaping feeds a build wave, it doesn't terminate the shift. So for every issue the shift only shaped (posted a proposal on), ask: did the shaping produce a dominant, buildable direction, or a genuine user-fork?
- Dominant buildable direction → this is leftover BUILD work, not done. Flag it: the shift should have run another wave and built it. "Shaped a near-buildable ~1-PR feature and stopped" is under-action, full stop. The bar is deliberately tight, so this does not fight the shift's shipping bias by branding every proposal under-action — force another build lap ONLY when all four hold: (1) small / independently shippable (roughly ≤1–2 PRs), (2) no strategic fork (the reviewer genuinely can't argue the direction down), (3) no material new discovery needed to build it, and (4) not blocked on anything in-flight. If any fail, it's a real proposal, not leftover work — leave it shaped.
- Genuine user-fork (building commits to a direction the user's input would change — a strategic bet, an irreversible/outward-facing choice) → correctly stops at shaped; it's a real proposal awaiting the user.
Do NOT let "it's an epic / it was shaped" launder buildable work into "done." The tell is when you can state the dominant next build with no open question — if you can, the shift left it on the table.
The loop
Every lap ends in exactly one of three outcomes — no lap may end open:
- Lens 2 found buildable work (survives the four-part filter above) → dispatch one concrete, finite work batch (fan out agents on that named set), then re-draft and re-review. This is the only outcome that starts another lap.
- Only decision defects (Lens 1) → fix the brief in place. No lap — decision polish never triggers a rebuild.
- Neither → publish under a named termination governor (below).
The forcing rule prevents the stall Codex flagged: a lap cannot keep discovering-and-reshaping forever, because each lap must either commit to a bounded build batch or terminate. "Keep reviewing until it feels drained" is not an outcome.
Termination governors — one MUST be nameable to publish
- No actionable-now work identified — Lens 2 comes back empty after the four-part filter. (This is a claim about what review found, not a proof the backlog is objectively drained — a markdown skill can't prove the latter. Say "no actionable-now work identified," never "backlog drained.")
- Budget — check
credit-pacing each lap; stop when the credit ceiling is reached and record it as a specific gate ("$X would fund the next lap"). If spend/budget is genuinely unreadable in this environment, say so — don't treat an unmeasurable governor as satisfied.
- Wall-clock — default ~8h, overridable by how the user framed the shift ("give it a couple hours while I'm at the gym"). Time is rarely the limiter — orchestration is fast; long runs come from slow underlying processes (e.g. local-AI bench sweeps), not from looping — so treat this as a backstop, not the plan.
Measure and report in the final brief: laps run, turns, wall-clock elapsed, and spend. If a governor stopped the loop rather than a real drain, say so explicitly.
Output
A revised brief (false gates struck, real gates sharpened, leftover work either done or listed), the review-provenance stamp (reviewer / primary-skipped-why / backup / reduced-strength?), the shift metrics (laps / turns / wall-clock / spend), the named termination governor that ended the loop, and — only once the loop has terminated — the go-ahead to publish. The published, reviewed brief is what the next shift-change opens on.
Dependencies
gate-check (decision-adjudication primitive) · credit-pacing (budget termination) · codex-pr (cross-model review pattern to generalize). Invoked by graveyard-shift; consumed by shift-change.
