The Loop This Book Teaches
Vibe coding has a loop too: describe, accept, run, describe again. It is fast, it feels productive, and Kai's third week is what it produces on code that has to live. The loop this book teaches has six stages: specify, context, generate, read, test, and commit or discard. Every one of them exists to catch something Kai's three weeks missed.
Chapters 3 to 9 each take a stage and do it properly. This page is the map: the stages, how they fit around the agent's own loop, why the chapters come in the order they do, and what each stage costs when it is skipped.
The Six Stages
Specify: write the task with its scope, its done-criteria, its constraints and what is out of bounds. Chapter 5. Context: make sure the agent sees what the task needs, the right files, the failing test, the decision Ines made yesterday. Chapter 4, with the project instructions file of Chapter 3 as the context every session starts with. Generate: let the agent work, inside permissions and a sandbox you chose. Chapters 1 and 3.
Read: read the diff as its author, knowing how generated code goes wrong. Chapters 6 and 7. Test: let tests you understand decide whether the change works. Chapter 8. Commit or discard: keep the result as a known-good step, or throw it away and go round again from the last one. Chapter 9.
One Pass of the Loop
One trip round the six stages is a pass, and a pass produces one reviewable step: a change small enough to read in one sitting, with the tests that show it works. The commit that ends one pass is the clean starting point of the next. If the pass goes wrong, the discard returns you to that same point, and nothing from the failed attempt leaks into the next one.
A task such as the refund change is several passes, not one large one. At Cragmoor it lands as three commits: boundary tests that pin down how the 24-hour rule behaves today, then one shared value replacing the two places the 24 lives, then the value becoming 12. Each commit is one pass. Each could be reviewed, and reverted, on its own.
Walk the first of those passes through the stages. Specify: add tests for the current 24-hour rule an hour either side of the line, at 23 and 25 hours before a class, and change no production code. Context: point the agent at refunds and its tests, and give it the one-file test command. Generate: the agent writes the tests and runs them. Read: you check that each test asserts what its name claims and that nothing outside the tests changed. Test: they pass against today's code, which is the point, because they describe today's behaviour. Commit. Twenty minutes, one small diff, and the next pass starts from a point where the current rule is pinned down.
Two Loops, One Inside the Other
The agent loop from Chapter 1, read, act, observe, repeat, is the agent's, and it runs entirely inside "generate". It can take two tool calls or forty, and from the outside it looks like one stage that took a few minutes.
The loop on this page is yours. The stages before "generate", deciding what to ask and what the agent needs to see, and the stages after it, reading, testing and deciding what to keep, are the ones no agent can do on your behalf. It can help with each of them: summarise a diff, run the tests, draft a task. Deciding that the diff is what you asked for, that the tests check what matters and that the change is worth keeping is the author's judgement, and the author is you.
The Order of the Chapters
Preparing the repository, Chapter 3, happens once per codebase, not once per pass. The instructions file, the commands, the permissions, the sandbox and the clean start are the ground every pass runs on, so the book lays them first.
The book then teaches context, Chapter 4, before specifying, Chapter 5, even though in a pass you write the task first. The reason is that what the agent can already see decides how much the task has to say. A task that names three files works because of what Chapter 4 teaches about selection; a task that says "the usual conventions" works only if the instructions file holds them. Learn what the agent sees first, and the task you write in Chapter 5 gets shorter.
Where Each Stage Fails
Each stage, skipped, has a characteristic failure, and you can usually name the stage from the symptom.
| Stage skipped | What goes wrong | In Kai's waitlist |
|---|---|---|
| Specify | It solves a neighbouring problem, or the easy half of this one | Two events at once was never part of the request |
| Context | It guesses, and contradicts code it never read | Each week-two session saw only the code, never the reasons |
| Read | You are vibe coding | 1,400 lines, read by nobody |
| Test | "Works" means "ran once" | The demo, and 30-odd unread tests |
| Commit or discard | Every later mistake is tangled with this one | Three large commits, all called "waitlist" |
Kai's waitlist skipped reading, testing and small commits, and was thin on the other two. That is why the double offer was hard to prevent, hard to find and hard to fix all at once. Any one of the stages, done properly, would have given the team a way in.
The table also works backwards, as a diagnostic. When a pass produces something wrong, ask which stage should have caught it before trying again. A diff that solved the wrong problem points at the task. A diff that ignored an existing helper points at context. A diff you only discovered was wrong in production points at reading and testing. Going round again without changing the stage that failed usually produces the same mistake in a different shape.
The Price of the Loop
The stages around "generate" add minutes to every pass. Reading a diff takes longer than accepting it, and writing a task with done-criteria takes longer than writing one sentence. Whether the trade is worth it is a real question, and the published evidence on what coding assistants actually save is mixed; Chapter 14 goes through it honestly.
What the loop buys is the speed of generation without the third week. The agent still writes the code in minutes. You still get the change faster than you would have typed it. What you no longer get is a feature that works on Friday and that nobody can explain or safely change three weeks later.
The agent loop is the cycle the agent runs: read, act, observe, until it judges itself done. It is fast, it runs without you, and nothing in it checks the work.
The loop is the cycle you run around it: specify, context, generate, read, test, commit or discard. It is slower, and it is the only one in which anyone checks anything. When this book says "the loop" without a qualifier, it means this one.
- "The loop is bureaucracy that cancels the speed." Generate is still the fast stage. The others add minutes per pass and save the days a third week costs.
- "The agent can do the read and test stages for me." It can run the tests and summarise the diff. Deciding that the tests check what you need and that the diff is what you asked for is the author's judgement.
- "One pass should deliver the whole feature." A pass is one reviewable step, and the refund change takes three.
- "Discarding a pass is a failure." Discard is a stage, not an exception. With a commit before you ask, throwing away a bad answer costs seconds.
- "The loop is only for big changes." For a change smaller than its explanation you skip the agent, not the loop: you still read, test and commit what you typed.
- End every pass with a commit or a discard. A half-kept pass is how unrelated changes tangle.
- Size each pass so the read stage fits in one sitting. Chapter 5 says how big that is.
- Do the stages in order even when the answer looks right. A fluent diff tempts you to jump from generate straight to commit.
- When a pass goes wrong, find the stage that failed before trying again. A bad answer usually traces to a vague task or missing context, not to bad luck.
Knowledge Check
The agent's refund change is correct, but it also rewrote error messages in two other modules that nobody asked about. Which stage should have caught this before commit?
- Test, because the suite should have failed on the changed messages
- Read, because the unrequested edits are visible in the diff itself
- Context, because the agent should have been shown fewer files
- Commit, because the commit step lists every file that changed
Where does the agent's own loop of read, act, observe sit in the book's loop?
- It replaces the book's loop whenever the agent runs on its own
- It runs across generate, read and test, which the agent handles
- It runs entirely inside the single stage called generate
- It runs once before specify, to gather context for the task
Why does the refund change land as three commits rather than one?
- Each pass makes one step small enough to read and revert alone
- An agent can only change one file in each commit that it makes
- Three commits make the history look more active to the team
- The test runner can only handle three changes at a time
Which stage can the agent not do on your behalf?
- Running the test suite and reporting the results it printed
- Summarising the diff into a short list of what it changed
- Drafting a first version of a task description to edit
- Deciding that the diff is what you asked for and worth keeping
Why does the book teach context in Chapter 4 before specifying in Chapter 5, when a pass starts with specify?
- Because in a real pass the context is gathered before the task
- Because what the agent already sees decides how much a task must say
- Because context is the easier topic and specifying the harder one
- Because context is set once per codebase and the task once per pass
You got correct