The Diff Is the Product
When the agent finishes, three things come back: the conversation, a summary and a change to the files. Only the change ships. The rest is commentary, written by the same agent that made the change.
Step three of the refund change, from Chapter 5, comes back with this summary: "Changed the refund window to 12 hours and updated the tests accordingly." Every word of it is true. The diff behind it also changes four behaviours nobody asked to change, and nothing in the summary hints at any of them.
Three Artefacts, One Product
The transcript records what was said and done in the session. The summary is the agent's account of what it did. The diff is what changed. Only the diff is merged, deployed, blamed when something breaks, and maintained for the next three years, so it is the only one of the three that the review decides on.
Why the Summary Is the Wrong Thing to Read
The summary is written by the same agent, after the work, and it compresses about 140 changed lines into one sentence. It describes intent. "Updated the tests accordingly" covers two edits that could not be more different: the 23-hour test, which changed because the rule changed, and the test for a gym in the second time zone, which changed because the code had started giving a wrong answer and the test was edited to agree with it. Both are "updated accordingly". Only one is correct.
A summary is rarely false in a way you can catch, because it says almost nothing checkable. That is not dishonesty on the agent's part; it is what a one-sentence account of a six-file change has to be. The fourth topic of this chapter takes the point further: no account the agent gives of its own work, however detailed, is evidence about the work.
The Diff as a Proposal
You committed before asking, as Chapter 9 will make a habit, so git can show exactly what changed against that commit, and nothing the agent wrote is accepted until you stage or commit it. The review is the decision Chapter 2 made you accountable for, not a formality before it.
Make the first command after any agent session the same every time: the status and the statistics, before the summary and before the transcript. It takes ten seconds, it shows every file that changed, and it gives you a picture of the change that the agent's account cannot colour, because you formed it first.
$ git status --short M src/cragmoor/booking.py M src/cragmoor/gyms.py M src/cragmoor/refunds.py M src/cragmoor/schedule.py M tests/test_refunds.py ?? src/cragmoor/policy.py $ git add --intent-to-add . $ git diff --stat src/cragmoor/booking.py | 4 ++- src/cragmoor/gyms.py | 3 +++ src/cragmoor/policy.py | 64 ++++++++++++++++++++++++++++++++++++++++++++++++ src/cragmoor/refunds.py | 20 +++++++-------- src/cragmoor/schedule.py | 2 +- tests/test_refunds.py | 49 ++++++++++++++++++++++++++++++++++-- 6 files changed, 128 insertions(+), 14 deletions(-)
$ git status --short M src/booking.ts M src/gyms.ts M src/refunds.ts M src/schedule.ts M tests/refunds.test.ts ?? src/policy.ts $ git add --intent-to-add . $ git diff --stat src/booking.ts | 4 +++- src/gyms.ts | 2 ++ src/policy.ts | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++ src/refunds.ts | 21 ++++++++-------- src/schedule.ts | 2 +- tests/refunds.test.ts | 47 ++++++++++++++++++++++++++++++++++-- 6 files changed, 128 insertions(+), 14 deletions(-)
$ git status --short M src/main/java/org/cragmoor/Booking.java M src/main/java/org/cragmoor/Gym.java M src/main/java/org/cragmoor/Refunds.java M src/main/java/org/cragmoor/Schedule.java M src/test/java/org/cragmoor/RefundsTest.java ?? src/main/java/org/cragmoor/Policy.java $ git add --intent-to-add . $ git diff --stat src/main/java/org/cragmoor/Booking.java | 3 +- src/main/java/org/cragmoor/Gym.java | 7 +++- src/main/java/org/cragmoor/Policy.java | 63 +++++++++++++++++++++++++++++ src/main/java/org/cragmoor/Refunds.java | 19 ++++----- src/main/java/org/cragmoor/Schedule.java | 2 +- src/test/java/org/cragmoor/RefundsTest.java | 48 +++++++++++++++++++++- 6 files changed, 128 insertions(+), 14 deletions(-)
Two details of that output matter before any line is read. The new file is marked as untracked, and a plain diff does not show untracked files at all: without marking it as intended for addition, the configuration object, more than sixty lines of it, would be invisible to the review. And the totals, six files and 128 added lines, belong to a step whose approved plan named two files and fewer than 20 lines.
Why Reading Became the Job
Writing 140 lines by hand took an afternoon, so the author had read every line by construction. The agent wrote them in about two minutes, and the reading no longer happens by itself. The time saved on typing is real only if the reading still gets done. In the supervised loop from Chapter 2, reading is now the longest stage, and Chapter 14 counts it as the cost nobody budgets.
This is the core engineering skill of working with an agent: reading a change you did not write, quickly and well enough to accept it or reject it with reasons. The rest of this chapter is how.
The arithmetic still favours the agent, by a wide margin, as long as the reading happens. A careful read of 140 lines takes perhaps twenty minutes; writing them would have taken an afternoon. Slow reading does not break the arithmetic. Skipping the reading does: accepting the two-minute diff on the strength of the two-line summary, and paying for it weeks later in a bug report from the front desk.
Reading a Diff You Did Not Write
Reading your own diff is checking that you did what you meant. Reading an agent's diff has no such anchor: you have no memory of intent and no sense of which lines were hard. So you rebuild intent from the task (Chapter 5) and the plan, and check the diff against both. The refund plan named two files, refunds and its tests. The diff touches six. That mismatch is a finding before a single line is read, and the cheapest one this review will produce.
Bring three things to the diff before opening it: the task, with its rule and its files out of bounds; the plan you approved; and the example table from Chapter 5. Each hunk is then read against something. Does this line serve the rule? Was this file in the plan? Which row of the table does this test pin? A hunk that answers none of the three questions is either a plan change nobody flagged or something the agent decided on its own, and the review has to say which.
When the Diff Is Too Big to Read
Chapter 5 defined a reviewable change and set Cragmoor's split point at about 200 changed lines. The refund diff is under that line in total and still about seven times the size of its plan, most of it a mechanism nobody asked for. A diff several times its plan gets skimmed, not reviewed, and the bugs sit in the skimmed part. The response is not to read harder. It is to make the diff smaller first, by keeping the hunks the plan described and throwing away the rest, which the last topic of this chapter does, and then to read what remains.
- "If the summary matches what I asked, the change is what I asked." The summary describes intent. The refund summary matched the task word for word while the diff carried a boundary flip, a time-zone change, a rounding change and a new configuration object.
- "The tests pass, so I don't need to read it." The passing suite includes tests the agent edited. The second-zone test passes because its expected value was changed to the wrong answer, and a green run is evidence only about tests you have read (Chapter 7).
- "Reading every line throws away the speed the tool gives me." The speed survives as long as reading is cheaper than writing, and it is. Skipping the read moves the cost to the third week (Chapter 2), where it is larger.
- "The team's code review will catch anything I miss." Team review assumes the author read their own change. When the author is an agent, the author's read is yours, and nobody else will do it.
- "A one-line request does not need a diff check." The agent decides how many lines to change. The request was one number; the diff was six files.
- Open the diff before the summary. Form your own view of what changed, then compare it with the agent's account, instead of reading the diff through it.
- Check the list of changed files against the plan before reading any line. A file the plan did not name is the cheapest finding in the review.
- Accept by staging the hunks you have read, never by "looks good". Staging is the record of what was actually reviewed (Chapter 9).
- Count the reading time when sizing a task. A change whose diff takes longer to read than to write by hand belongs to the last topic of Chapter 5.
Knowledge Check
The agent's summary says "changed the refund window to 12 hours and updated the tests accordingly", and every word is true. How can the change still be wrong?
- It cannot, as long as the summary and the task both describe exactly the same refund rule
- The summary compresses many changed lines into intent, so extra behaviour changes fit under it
- Summaries are generated before the work is finished, so they describe an older plan of the work
- The agent hides the unrelated changes from its summary on purpose, so that they get merged
The refunds tests are green after the agent's change. The diff also edits two expected values in the tests. What does the green result tell you?
- That the change is correct, since every single test in the suite now passes on it
- Nothing at all, because a green suite never tells you anything useful about a change
- Only what the tests you have read assert; the edited ones may agree with a wrong answer
- That the edited tests were updated correctly, or else the whole suite would have failed
The approved plan named refunds and its tests. The diff touches six files. What does that mismatch tell you before you read a line?
- The diff does things the plan did not agree to, and each extra file needs a reason
- The plan was too narrow, so the agent was right to widen the change to six files
- Nothing yet; the number of files says nothing until you have read every changed line
- The agent misunderstood the task and the whole diff should be thrown away now
A diff is about seven times the size of its plan, mostly a mechanism nobody asked for. What is the best first move?
- Read it twice as carefully, since it is bigger than expected and more likely wrong
- Merge the parts that pass the tests and review the rest after it has shipped
- Make it smaller first: keep the hunks the plan described, then read what remains
- Ask the agent to summarise the diff in more detail before you read any of it
When does the cost of reading a diff make writing the change yourself the better choice?
- Whenever the diff is more than a few dozen lines, whatever the change is
- Never, because reading code is always faster than writing the same code
- Only when the agent has already failed at the same task at least twice
- When reading the diff would take longer than writing the change by hand
You got correct