| name | engineering-requirements |
| description | Use before any spec or non-trivial change becomes code — dispatches the principal-engineer bench (17 specialist seats) to return the engineering requirements the author did not know to ask for, merges them into a machine-checked engineering.md, and gates the build on it. Fires on "/bench", "/boris", "engineering requirements", "engineer this", "what am I missing", "review this properly", and automatically from /spm before a spec is final. |
| argument-hint | <path to spec.md or a change description; defaults to ./spec.md or the branch diff> |
| allowed-tools | Read, Grep, Glob, Bash, Write, Agent |
| updated | "2026-07-29T00:00:00.000Z" |
engineering-requirements — the bench gates the build
The planning pipeline converts what the author said into a better-organised version of what the
author said. This skill performs the move nothing else performs: generating the requirements
nobody thought to ask for — then refusing to let the change become code until they are answered.
A bench, not a reviewer. Seventeen seats, each a principal engineer in one speciality, run in
parallel as independent lenses. The roster, ownership map and dispatch predicates live in
references/bench.md; the shared output contract lives in
~/.claude/agents/bench/CONTRACT.md.
Why a bench and not a longer prompt: on 2026-07-29 a generalist review of an RLS incident concluded
the exposure was limited to application-encrypted OAuth tokens. A drift lens on the same repository
in the same hour found nine surviving "Anon read access" policies, sourced from an untracked
bootstrap file the generalist never opened, exposing 11,007 rows of plaintext client financial
data. Breadth is not depth repeated.
Procedure
1. Locate the change
$ARGUMENTS if given; else ./spec.md; else the branch diff against merge-base. If there is
neither a spec nor a diff, say so and stop — this reviews something, it does not invent it.
2. Select the seats
Apply the predicates in references/bench.md against the changed paths, the
spec text, and the repo. The core four (boris, eng-failure, eng-observability, eng-test)
always sit. Everything else is earned.
Announce the seated bench and why, in one line each. Selection is auditable or it is vibes.
eng-release seats unconditionally when the migration ledger disagrees with the migration
directory. That is a standing condition, not a kind of change, and it is the exact failure that
let a correct security migration sit unapplied for five and a half months. Determine it by running
the check, not by judgement:
python3 ~/.claude/skills/engineering-requirements/scripts/migration_drift.py check \
--root <repo> --db-url "$DRIFT_DB_URL"
Exit 0 in sync, 1 drift — seat eng-release, 2 cannot determine — also seat eng-release, and
say so. A check that cannot see the database is the same silent fail-open it exists to catch, so
"we could not tell" seats the reviewer rather than excusing him.
If more than ten seats are earned, stop and return a decomposition instead of a review: a change
that spans the whole bench is too big, and that is itself the finding.
3. Run them cold, in parallel
Spawn each seat with the Agent tool, subagent_type: "<seat name>", in a single message so
they run concurrently. Give each: the change, the repo root, round: 1, and nothing else — no
summary of the change, no account of why it was written that way, no other seat's findings. A seat
that has read another seat's output is no longer an independent lens, and a warm reviewer inherits
the author's rationalisations.
If a seat's subagent_type is not found, the agent registry loaded before the bench existed —
spawn general-purpose on Opus and open with "read ~/.claude/agents/bench/<seat>.md and
~/.claude/agents/bench/CONTRACT.md, and adopt them completely for this task." The registry picks
the bench up at the next session start.
Do not review it yourself. A model grading its own planning output is the failure this exists
to prevent.
4. Merge into one artifact
Write engineering.md beside the spec. Every category carries by: naming the seat that answered
it, so coverage is auditable and a finding can be traced to a lens.
---
type: engineering-requirements
spec: ./spec.md
spec_sha256: <shasum -a 256 of the spec exactly as reviewed>
reviewer: bench
seated: [boris, eng-data, eng-authz, eng-failure, eng-observability, eng-test]
reviewed_at: <ISO-8601 with offset>
status: BLOCKED
categories:
data_model: {state: PRESCRIBED, ref: "#data-model", by: eng-data, blocking: true}
invariants: {state: DECIDED, ref: "#invariants", by: eng-authz}
failure_modes: {state: DECIDED, ref: "#failure-modes", by: eng-failure}
interface_contract: {state: , , }
{ , , }
{ , , }
{ , , }
{ , , }
{ , , }
{ , , }
All ten categories, every time — a category no seated specialist owns falls to the chair, so the
contract never weakens because the bench was small. Then one ## section per
DECIDED/PRESCRIBED category matching its ref anchor.
status is derived from blocking, never chosen. Record disagreements rather than averaging them.
5. Run the gate
python3 ~/.claude/skills/engineering-requirements/scripts/engineering_gate.py --spec <spec.md>
Exit 0 = PASS. Exit 1 = BLOCKED, reasons on stderr. Fix the artifact, never the validator — if
the gate is wrong that is a bug, and the fix starts with a failing test.
6. Report
State what the bench found that the change did not contain, and which seat found it. That sentence
is the whole value of the layer; if there is nothing to say, say that too — it is a real signal
that either the change was already good or the bench is mis-calibrated.
The ten categories
data_model · invariants · failure_modes · interface_contract · concurrency ·
migration · rollback · observability · budget · test_oracle
Legal states: DECIDED + ref (the change answers it, and the section quotes it), PRESCRIBED +
ref (a seat supplies the answer), DEFERRED + reason, N/A + reason. Definitions and worked
examples in references/categories.md.
PRESCRIBED is not a softer DECIDED. It marks a requirement a reviewer invented, so you can
overturn it without re-triggering review. A fabricated latency budget filed as DECIDED ends up on
a dashboard as fact.
Most changes are small, and a short review passes. On something that writes nothing to disk,
data_model/migration/concurrency being N/A is the correct output. The gate exists to stop
silent skipping, not to extract ten paragraphs from a CLI flag.
Where this binds
| Point | Behaviour |
|---|
/spm step 7a | A spec is not final until the gate exits 0. |
pr_release_gate.py | If the branch diff adds or edits a spec.md, its sibling engineering.md must exist and validate before push or PR. |
| Everything else | Inert — no spec in the diff, no gate. |
Scoping to the branch diff is what makes "new work only" true: a spec that predates the bench and
is untouched does not block, and editing one pulls it back into scope, which is correct because the
review binds to content rather than to a date.
Scope
- Seats are read-only and never edit code.
- This does not replace
judge (should we build this?) or spm (what should we build?). It
answers what will break when we do.
- Adding a seat requires naming a failure class the existing seventeen provably missed, with the
incident that proves it.
