A Task an Agent Can Finish
"Change the refund window to 12 hours" is a sentence a colleague would answer with four questions. An agent answers it with a diff. Whatever the colleague would have asked, the agent decides for itself, silently, and you find out which way it decided when you read the change.
A task an agent can finish states its scope, what done means, the constraints and the files out of bounds, so those questions are answered before the work instead of discovered in review. The refund change, written three ways, shows the difference each part makes.
The Four Parts
Scope is the behaviour that changes and where: a full refund for cancellations up to 12 hours before the class, and the cancellation screen showing the same deadline. Done-criteria are checks a command can run: these tests exist and pass, and the full suite shows no new failures. Constraints say how: no new dependencies, keep the public functions of refunds as they are, follow the surrounding style. Out of bounds says what not to touch: pricing, the migrations directory and the two schedule tests that already fail on main, from Chapter 3.
Each part prevents a different wrong diff. Missing scope produces a change to the wrong thing. Missing done-criteria produces a change that stops when the agent feels finished. Missing constraints produce a correct change in a shape the team will not merge, and a missing out-of-bounds list produces a correct change with an unrequested edit to pricing inside it.
Version One: The Sentence
"Change the refund window from 24 to 12 hours." The agent edits the constant it finds, changes the tests that asserted 24 so they assert 12, adds no test at the new boundary, and reports success. It answers no question it was not asked. The second copy of 24 in booking survives, as it did in Chapter 4, and nobody has decided whether bookings made before the change get the old window or the new one. The diff decided it by accident: whatever the code does now is the policy.
Version Two: The Essay
Burned by version one, the temptation is to dictate everything: "add a constant for the window in hours, then in the deadline function at line 88 of refunds replace the hard-coded value with the constant, then in booking..." for a page. You have written the code in English. The agent follows it literally, including the line number that moved when Ines merged a change last week, so one edit lands in the wrong function. And nothing is left for the agent to do well. It reads the code faster than you can describe it and would have found the right lines itself.
Over-specifying the how costs as much as under-specifying the what. The page you wrote is a design you did not review, and the agent has no way to tell you the design is wrong, because you asked it to follow, not to think.
Version Three: The Task
About ten lines. The goal and its business reason. The rule, with Ines's answer to the question the second run raised in Chapter 4: the 12 hours apply to every cancellation from the day the change ships, whenever the booking was made, so no date switch is needed. The examples, which the fourth topic of this chapter turns into a table. Done as commands, the files out of bounds, and one instruction that matters more than it looks: ask rather than guess when a business rule is unclear.
Goal: the full-refund window becomes 12 h before class (now 24). Why: the 24-hour rule causes most refund complaints. Rule: up to 12 h before the class, inclusive, refunds in full; later refunds nothing. Applies to every cancellation from the day this ships, whenever the booking was made. The cancellation screen shows the same deadline. Examples: the table in the ticket; one test per row. Done: those tests pass; the full suite passes apart from the two known schedule failures. Constraints: no new dependencies; keep refunds' public API. Out of bounds: pricing, migrations, the schedule tests. If a business rule is unclear, stop and ask. Do not guess.
Nothing in it says how to write the code. Everything in it says what must be true when the code is written, and what must not change on the way.
Ten lines take about five minutes to write, and most of those minutes go on the rule, not the format. That is the real work the sentence in version one skipped: deciding what "12 hours" means at its edges, who it applies to, and what else has to agree with it. The agent cannot do that part for you, because the answers are business decisions, and nothing in the code records them.
Why "Done" Must Be Checkable
The agent loop from Chapter 1 stops when the model judges the task complete. That judgement is generated like everything else the model produces, and it can be wrong with full confidence. Done-criteria that are commands turn the judgement into a check: the agent runs them before it stops, and you run them before you read. "Make it work" has no check. "These four tests pass and the suite is green" does, and it costs one line of the task.
A checkable done also protects you from a quieter failure: the agent stopping early. Long tasks drift (Chapter 4), and a drifted agent can declare a task finished with one step still undone, in the same confident tone it uses when everything is done. "These tests pass" catches that. The agent runs the command, sees a failure, and keeps working, or it reports the failure honestly, and either outcome is better than a summary you cannot check.
Out of Bounds Is an Instruction, Not a Wall
The agent usually respects "do not touch pricing". Usually is the important word. The line is a request in the context, with the same standing as every other line, and Chapter 4 showed what happens to early requests in a long session. So you verify it in the diff, with the questions of Chapter 6. Where a boundary must hold, something has to enforce it: a permission from Chapter 3, a test that fails when the boundary is crossed, or a code-owner rule that sends any change to pricing to a named reviewer.
Ask Rather Than Guess
The last line of version three looks like politeness and does real work. Without it, an agent that meets an unclear rule picks a plausible reading and carries on, and the reading becomes the policy. With it, the agent stops and writes the question, usually in the plan, sometimes halfway through a change. Answer it, and put the answer into the task file, not only into the chat, so the next session reads it too. At Cragmoor, the existing-bookings question was answered this way once, by Ines, and it never came up again.
- "A short request leaves the agent room to be clever." It leaves room to guess, and the guesses land on the points you did not think about, which are exactly the points that needed a decision, such as which bookings the new window covers.
- "A detailed task should say how to implement it." Say what must be true and what must not change. Dictating the how removes the agent's one advantage, reading the code fast, and copies your mistakes into the change.
- "The agent will ask if something is unclear." It often picks a plausible reading and carries on, unless the task tells it to stop and ask.
- "Done-criteria are for big tasks." A one-line change without a check is still only a claim. "The full suite passes" is one line of task.
- "The constraints are obvious from the codebase." The agent infers style from the files it read. A team rule such as "no new dependencies without review" it cannot infer at all.
- Write every task with scope, done-criteria, constraints and out of bounds. Four lines are enough for a small change, and each prevents a different wrong diff.
- State done as commands: named tests and the full suite, so "finished" is something both of you can run.
- Say what must be true, not how to write it. Leave the implementation to the agent and check it in review.
- Tell the agent to ask before guessing a business rule. The existing-bookings question has an answer only Ines can give.
Knowledge Check
You send "change the refund window from 24 to 12 hours" and nothing else. What does the resulting diff most likely contain?
- A plan for the change and a question about bookings made before it ships
- The constant and its old tests changed, with no new boundary test at all
- Changes to
refunds,booking, the cancellation email and the schedule page - Nothing at all, because the request is too short for the agent to act on
A task reads: "Full refund up to 12 hours before the class. The full suite must pass. No new dependencies." Which of the four parts is missing?
- Scope: it never says what behaviour the refund change is meant to alter
- Done-criteria: it never says anything a command could run to check the work
- Out of bounds: it never names
pricing, the migrations or the failing tests - Constraints: it never says anything about how the change should be made
Why does a task that dictates the implementation line by line tend to backfire?
- The agent follows it literally, stale line numbers and design mistakes included
- The agent ignores detailed instructions and writes its own design regardless
- Long tasks are cut off by the tool, so the second half of the instructions is lost
- Detailed tasks make the agent ask so many questions that the work never starts
Which done-criterion lets both you and the agent check the refund change?
- The refund rule matches what Ines asked for in her note on the ticket
- The change is clean and as small as it can be, with nothing left over
- The tests for each table row pass, and the suite shows no new failures
- The agent reports that it has tested the change and is confident in it
You got correct