Scope gate

Every other check answers "is this diff good?". This one answers "is this the right diff?" — and explains the answer to someone who may not read code.

Run it before writing code. Run it again before opening a PR if the shape changed. It ends by stopping and asking; it never approves silently and never decides for the user.

Read .claude/scope-gate/invariants.md first. If it is missing, say so and suggest /scope-gate-setup — then continue with steps 1–3 and the two structural tests, which work without it.

Step 1 — Restate the outcome, in the user's words

One sentence: what the user will be able to observe when this is done.

Their words, not the problem class. "I want to hear Hokkien" is the outcome. "Integrate a TTS provider" is a solution already chosen — if you restate it that way, the gate is dead on arrival because every option you generate will be a variation of that solution.

If the request genuinely is the general capability, say so explicitly. Some asks really are "build the integration," and the gate should not pretend otherwise — it just changes which questions matter (skip to the structural tests).

Step 2 — Find the smallest thing that produces that outcome

List real options. At least one must involve no code at all. If you cannot find a zero-code option, say what you ruled out and why — "no configuration reaches this" is a finding, not a formality.

Zero-code options that keep turning out to be the answer:

• Create or edit a record — an agent, a workspace setting, a feature row
• Use an existing UI action nobody remembered
• Change an environment value
• Do it manually once, and see whether it is even wanted before automating

For each option: what it delivers, what it does not, and roughly how big.

Step 3 — Size it

Estimate the planned change in files and lines, against the smallest option.

Smallest:  <n> files / ~<n> lines  — delivers: <what>
Planned:   <n> files / ~<n> lines  — delivers: <what>
Ratio:     <n>×

Over ~3× is not forbidden. It is a claim that needs a stated reason, and the reason has to be about this request, not about tidiness. "While I am here" and "for consistency" are how a one-file fix becomes a fifty-file PR.

Step 4 — Match invariants by effect

Walk .claude/scope-gate/invariants.md and select by what the change makes true, never by which files it touches. A change to a dropdown and a change to a route are the same event if both make a capability reachable.

Ask of the planned change:

• Does anything become selectable, visible, or callable that was not?
• Does a credential travel anywhere new, or get chosen by new logic?
• Does it touch something shared — a registry, an auth path, a policy — that other features already depend on?
• Does it change what happens when a check fails?

Pull only the invariants that match. Two relevant ones beat twelve listed.

Step 5 — Two structural tests

These apply even with no invariant index, and between them they account for most blocked pull requests.

Exposure. Does this let a user reach something they could not reach before?

The moment a capability becomes selectable, every pre-existing weakness behind it becomes yours. Weaknesses that were tolerable while unreachable become release blockers the instant someone can click them.

If yes: name what is behind it and what is missing there today. Those are now your blockers, not the previous author's.

Shared mechanism. Does this ride on machinery other features already use — credential resolution, an auth route, a provider registry, a policy envelope?

Using shared machinery means inheriting its unfinished business. If that machinery has a known weakness, adding the Nth user of it is the change that makes the weakness visible — and reviewable.

If yes: name the weakness, and decide whether this change fixes it, works around it, or should wait.

Step 6 — Say it so a non-architect can act on it

Write the report in the language the user is speaking. No identifiers, no file paths in the body, no architecture vocabulary unless you define it in the same breath. The reader should be able to make a decision without opening the code.

Translate mechanisms into consequences:

Use this shape:

What you asked for
  <the observable outcome, their words>

Smallest way to get it
  <option> — <size> — <what it does not cover>

What is planned
  <size>, of which <the part that is not the smallest option> is <what>

⚠️ <only if something matched — otherwise omit this block entirely>
  <plain-language consequence>
  <what is behind it that is unfinished, in plain language>

Suggestion
  <one concrete recommendation>

Keep it short enough to read in under a minute. A gate that produces a document gets skipped, and a skipped gate is worse than none because it manufactures the appearance of diligence.

Step 7 — Soft reject

If the ratio is above ~3× or any invariant matched or either structural test came back yes: present the report, then stop and ask. Offer exactly:

• Smallest — do the minimal thing now, file the rest
• As planned — proceed, with the reason recorded (say it will go in the plan and the PR description)
• Split — ship the outcome first, generalise separately

Then wait for an answer. Do not pick one. Do not proceed while explaining why proceeding is fine.

If nothing matched and the ratio is sane, say so in two lines and get out of the way.

What this is not

• Not code review. Say nothing about naming, structure, tests, or bugs. Those have their own tools and those tools work.
• Not a veto. The user decides. A stated reason converts a concern into a recorded decision, and that is a complete outcome.
• Not a form to fill in. If the honest answer to step 5 is "no, nothing is exposed, nothing is shared," the whole gate is four lines. Length is not rigour.

Anti-patterns seen in practice

• Restating the ask as the solution you already chose. Poisons every step after it.
• Passing the gate by writing a long justification. If the reason needs three paragraphs, it is not a reason, it is a rationalisation. Recommend the split.
• Applying a completeness rule to a scope you never decided. "Register the provider everywhere" is correct after you have decided to ship the provider. Applied to a request that only needed an audition, it is how you get a fifty-file change. Scope first, then completeness within it.
• Treating green checks as scope evidence. Passing tests, clean typecheck, and an approving review say the diff is well-made. None of them say it should exist.