batch-gate

/batch-gate

Gate a batch of elaborated features before handing them to implementation.

Every other review in this family looks at one unit: /feature-review enforces per-feature detail, /epic-review checks one epic's coherence, /canon-audit stress-tests the canon itself. None of them ever sees the handoff batch — the 5-10 features about to go to implementation together, possibly spanning epics. Ten features can each individually PASS while two of them modify the same contract incompatibly, while the batch collectively opens a security surface no single Security section declares, or while the batch still doesn't deliver the client requirement it was supposed to.

This skill is the last look before the work becomes expensive. It is judgment work, not checklist work — run it with the strongest available model. It is a gate, not a fixer: advisory only, one pass, no auto-fix, no convergence loop. If it blocks, route the fixes downstream (/feature-elaborate → /feature-review, or an epic/canon-level decision), then re-run the gate once.

This skill is repo-agnostic. It reads .claude/repo-conventions.yaml at Step 0 and loads the canon via the same manifest /get-context uses (docs/context/canonical.yaml).

Usage

/batch-gate <feature-path> <feature-path> ...     # explicit batch
/batch-gate <epic>                                # all status: ready features in the epic
/batch-gate <epic-a> <epic-b>                     # cross-epic batch
/batch-gate <epic> --status ready,in-progress     # widen the status filter (explicit opt-in)

Each argument that resolves to an epic folder contributes its status: ready features (or the --status set); each argument that resolves to a feature folder contributes itself. Mixing is fine.

What this skill is NOT

The single most important discipline in this skill is restraint:

• It does not re-litigate /feature-review. Missing sections, placeholder content, file-path accuracy, test layers, ADR-007 routing, effort sizing — all assumed already enforced. Re-deriving them burns the strong model's run on findings a cheaper pass already made.
• It does not replace /epic-review. Intra-epic coherence, feature split, goal drift — epic-review territory. The gate only re-enters that ground when the batch crosses epics or when a batch-level interaction makes an epic-level finding urgent now.
• It does not fix anything. No edits to proposals, designs, statuses, or the canon. The only file it writes is its own report.

Altitude rule (hard): every finding must cite two or more features, or one feature against a canon doc / client requirement at batch-delivery level. A finding about exactly one feature's internal quality is out of scope — list it in one line in the report's routed-items appendix and move on.

Procedure

Step 0 — Read repo conventions

Read .claude/repo-conventions.yaml at the repo root (if present): backlog_root (default backlog), docs.*, and backlog.feature_lifecycle. Defaults apply when missing. Every backlog/ path below means the backlog_root value read here.

Step 1 — Resolve the batch and check preconditions

Resolve every argument to a set of feature folders. Epic arguments resolve the way /epic-review resolves them: if given a bare name (e.g., email-platform), look in backlog/<name>/ first, then walk backlog/phase-*/<name>/, then backlog/deprioritised/<name>/ (deprioritised is a sibling of the phases — a phase-* glob does not match it); if given a path, use it directly; if the folder does not exist, list available epics from backlog/ (top level + each phase-*/ + deprioritised/) and ask the user to confirm. A resolved epic contributes the features under its features/ subfolder, filtered by status. Then verify the gate's premise holds for each feature:

• proposal.md, design.md, tasks.md all exist (the batch is elaborated).
• status: ready — or the user explicitly widened the filter / passed the path directly.

A feature failing either check is a precondition finding: the gate assumes detail review already happened, and for that feature it didn't. Report precondition findings immediately and exclude those features from the lenses (gate the rest) — unless exclusions would gut the batch (>⅓ of it), in which case stop and report: the batch isn't ready to gate.

A batch of one is legal but unusual — say so and suggest /feature-review is probably the right tool, then proceed if the user asked anyway.

Step 2 — Load the canon

Load the canon exactly as /get-context does: read docs/context/canonical.yaml, load every flagged doc, expand globs. Override the hard-stop (same override /canon-audit uses): contradictions that would stop get-context are collected as findings for this report, and the run continues.

If there is no manifest: the interactions and security lenses still run (against code and the batch itself); the architecture and coverage lenses run degraded against whatever product/phase/requirements docs you can find, and the report must say so plainly and recommend authoring the manifest.

Step 3 — Read the batch

Read every feature's proposal.md and design.md in full; skim tasks.md for sequencing and shared-file signals. Also read: each parent epic's README (goals, exit criteria, dependencies section), any decisions/ ADRs those epics carry, and the phase plan if the canon flags one.

Step 4 — Lenses

Fan out one agent per lens (Workflow tool when available, Agent tool otherwise). Each agent gets the loaded canon, the batch plans, code-read access, and its charter below. Charters are floors, not ceilings — but the altitude rule binds every agent.

interactions — what the features do to each other

• Contract and schema conflicts: compare every design's files-to-modify lists, migrations, event/API contract changes. Two not-yet-implemented features touching the same contract, table, or module need either an explicit ordering or a merge — flag the silent case.
• Migration collisions: two features each adding migrations that assume the other doesn't exist (chain position, column ownership, data backfill ordering).
• Duplicate solutions: two features quietly solving the same problem different ways (often visible as similar new modules/helpers in different designs).
• Dependency ordering: the depends-on DAG across the batch (including cross-epic edges) resolves, is acyclic, and is consistent with the order the batch will actually be implemented in. A dependency on a feature outside the batch that isn't already done is a finding — the batch can't deliver without it.
• Orphaned shared assumptions: every feature assumes some shared piece (a config surface, an auth helper, a queue) exists or "another feature" builds it — and no feature in the batch actually builds it.

architecture — does the batch build toward the target?

• Take the canonical target architecture and overlay the sum of the batch's designs: does the batch move the system toward the target or accrete away from it? Name the load-bearing assumptions the batch makes about the target.
• Decisions smuggled in at batch scale: the same undeclared contract/technology/pattern choice appearing in two or more designs is a de-facto ADR nobody wrote. One design choosing locally is feature-review territory; the batch converging on an unrecorded decision is yours.
• Batch-introduced coupling: after this batch, which modules newly know about each other? Is that coupling in the target architecture or an accident of parallel authorship?

security — the surface the batch composes

Per-feature Security sections can each honestly say "no new surface" while the batch composes one. Audit the composition:

• Enumerate what the batch collectively introduces: new endpoints, new data flows, new stored data, new secrets/credentials, new agentic/tool/LLM surface, new egress. Map each against the canon's declared controls — what does the composed surface touch that no declared control reaches?
• Cross-feature flows: feature A stores or produces what feature B exposes, executes, or sends — trace untrusted input across feature boundaries (including prompt-injection paths if any feature touches an LLM/agent surface).
• Privilege and tenancy: does the batch's combined behaviour widen any identity's effective access beyond what any single design declared?

coverage — does the batch deliver what was asked?

The findings nothing else in the pipeline can catch:

• Map the batch against the phase plan / client requirements / epic exit criteria (epic-criteria frontmatter where present, prose-matching otherwise): what does this batch claim to deliver, and which committed requirement is conspicuously in no feature? A missing requirement the client is expecting is a Critical finding.
• The reverse: features serving no stated requirement (legitimate for infra/tech-debt — say so rather than forcing a mapping; flag only when the unmapped work displaces committed scope).
• Sequencing against the phase plan: is this the right next batch, or does it deliver phase-N+1 scope while phase-N commitments sit unstarted?

Step 5 — Adversarial verification

Every Critical and High finding is verified by an agent independent of its author, refute-stance:

• A "conflict" that the plans already sequence explicitly (depends-on, an ADR, a stated ordering) is the system working, not a finding.
• A "missing requirement" must survive a search of the whole backlog — if it's delivered by a feature outside the batch or explicitly deferred with a recorded decision, the finding dies (report the deferral only if its priority looks wrong).
• A "composed security surface" must name the concrete path, not a vibe.
• Unverifiable findings are tagged UNVERIFIED and cannot drive a NO-GO.

Severity after verification: Critical = implementing the batch as planned causes rework, a security hole, or a missed client commitment. High = real, but containable by a condition carried into implementation. Advisory = worth a line, blocks nothing.

Step 6 — Verdict and report

Mechanical verdict rule (so gates are reproducible): any verified Critical → NO-GO; else any verified High or a non-empty exclusion list → GO-WITH-CONDITIONS; else GO. Precondition findings from Step 1 are listed first and excluded features named. Each excluded feature is itself a condition row (owner: route it through /feature-elaborate → /feature-review, then re-gate) — "we gated 6 of the 8 you asked about" must never read as a clean GO.

## Batch Gate: <label>  (<date>)

**Batch:** N features — <list, with epic prefixes if cross-epic>
**Excluded (preconditions):** <list + reason, or "none">
**Canon:** <manifest loaded / degraded — no manifest>
**Verdict:** GO | GO-WITH-CONDITIONS | NO-GO

### Blocking findings (Critical)
| # | Lens | Finding | Features | Route |
|---|------|---------|----------|-------|
| 1 | <lens> | <finding> | <feature(s)> | <e.g. "rework X via /feature-elaborate, re-review, re-gate" / "epic-level decision needed" / "canon fix — see /canon-audit"> |

### Conditions (High) — carry into implementation
| # | Lens | Condition | Features | Owner |
|---|------|-----------|----------|-------|
| 1 | <lens> | <condition> | <feature(s)> | <implementer instruction / specific feature's plan> |

### Advisory notes
- <one line each, or "none">

### Coverage map
| Requirement / exit criterion | Delivered by | Status |
|---|---|---|
| <req> | <feature(s) / NONE> | covered / partial / **missing** / deferred (recorded) |

### Routed out of scope (single-feature items — not gate findings)
- <feature>: <one line> → /feature-review

### Next steps
1. <ordered: what unblocks the handoff>

NO-GO and GO-WITH-CONDITIONS reports must make the path to GO concrete: every Critical has a route, every condition has an owner. A GO report should be short — don't pad it.

Step 7 — Persist

Write the full report to docs/reviews/<YYYY-MM-DD-HHMM>-batch-gate.md (timestamped to the minute), plus a compact snapshot table the next gate can diff against:

## Snapshot
| Feature | Epic | Status | Verdict contribution |
|---|---|---|---|

Commit it (chore(reviews): batch-gate snapshot <date>) only when the working tree is otherwise clean and HEAD is the repo's default branch; in any other state, leave the file written and tell the user it needs committing.

Hard rules

1. Advisory only. The gate never edits plans, statuses, or the canon. Its only write is its own report.
2. No loop. One pass, one verdict. After fixes, re-run the gate once — convergence loops live in /feature-review, not here.
3. Altitude is enforced, not aspirational. A finding citing one feature's internal quality goes to the routed-items appendix as one line, never into the findings tables.
4. Verdicts are mechanical. Critical → NO-GO; High or excluded features → conditions; else GO. No vibes-based overrides in either direction; if a finding doesn't justify its severity, fix the severity, not the rule.
5. Unverified findings never block. A NO-GO must rest entirely on adversarially verified Criticals.
6. Gates persist. Every run writes its docs/reviews/ snapshot so re-runs and future batches can diff.