Declare the change-set before you touch anything

Scope controlModel-agnosticupdated 2026-08-28sha dc9a99fd2a86

Breaks when: A declared scope is only as good as the understanding behind it, so an agent that has misread the task will declare a confident, tidy, wrong scope and then prove it stayed inside it – this catches drive-by edits, never a wrong plan. The renegotiation branch is the soft spot: an agent that finds the real fix outside its scope on every task has either been scoped too tightly or is using the branch as an escape hatch, and only you can tell those apart. Formatters, code generators, lockfiles, and import sorters produce legitimate out-of-scope hunks; without naming them up front the final audit drowns in noise and you start waving it through, which is worse than not running it. It also says nothing about whether the change is correct – a diff can sit perfectly inside its declared bounds and still be wrong.

The dangerous agent diff is not the one that breaks the build. It is the one that does the thing you asked plus four things you did not, each defensible on its own, none of them reviewed. You approve it because the first hunk is right and the file count is plausible. This makes the boundary a thing that exists before the work rather than a thing you reconstruct afterwards from a diff you are already tired of reading.

Before you change any code, you are going to declare the change-set. You may not edit anything until the declaration exists, and at the end you must prove the diff matches it.

TASK: {{task}}
REPO: {{repo_path}}
HOW TO RUN THINGS: {{verify_cmd}}

STEP 1 - Declare, before touching anything.
Output a scope block with exactly these five parts. Keep it short enough to read in thirty seconds.
- FILES I WILL EDIT: the explicit list. Not a directory, not a glob - the files. If you cannot name them yet, say what you must read first, read it, then declare.
- FILES I EXPECT TO CREATE: explicit paths, with one line each on why a new file rather than an edit.
- WHAT I WILL NOT TOUCH: the adjacent things you can already see are tempting - the neighbouring helper that could be tidied, the inconsistent naming next door, the test that has always been ugly. Name them so they are refusals on the record, not decisions you make quietly at line 200.
- INVARIANTS: the behaviour that must be identical afterwards. Public signatures, output shapes, on-disk formats, error semantics, anything a caller depends on.
- MACHINE-GENERATED HUNKS I EXPECT: formatter output, lockfiles, generated clients, import sorting. Name them now, or they will pollute the STEP 3 audit and train us both to skim it.

STEP 2 - Do the work, inside the declaration.
- If the task genuinely cannot be completed inside the declared scope, STOP and renegotiate: say what you found, what it would take, and what you recommend. Do not silently widen the scope and mention it in the summary. A renegotiation is a normal outcome; a quiet expansion is a failure of this task.
- If you find a real problem outside scope, write it down as a note. Do not fix it. An unrequested fix costs the reviewer more than the bug did.

STEP 3 - Prove the diff IS the declaration. This is the gate.
- Produce the list of changed files from version control, and set it against the STEP 1 lists. Any file present in the diff and absent from the declaration is a finding - report it before you report success, and either revert it or justify it in one line.
- Walk every hunk. For each one: which declared goal does it serve? A hunk that serves none is a drive-by, whatever its merits. Say so and revert it.
- For each INVARIANT, state how you confirmed it still holds and paste the evidence. "Unchanged" without a command or a quoted line is an assertion, not a check.
- Run {{verify_cmd}} and paste the real output with its exit status.

RULES.
- Never widen the declaration retroactively to make the audit pass. If the diff outgrew the scope, the honest report is that it did.
- Reverting your own out-of-scope work is a success, not a loss. Say what you reverted and why it was tempting.
- Formatting-only churn in a file you had to edit anyway is still churn. Keep it out unless the repo enforces it.

END WITH: files declared, files changed, any difference between the two, and one line on whether a reviewer can read this diff without holding the whole task in their head.

Fill in: task repo_path verify_cmd

Shared as is, for reference. Read it and decide what it will do before you run it; using it is your responsibility, under the terms.