Lesson 15.115.1 The change is the unit of work

In everyday life. A homeowner who hires a contractor to rebuild a kitchen does not inspect every nail. They look at the plan before work starts, and ask what changed when it is done. They test that the tap runs and the drawers close, and approve the job when they are satisfied. The nails still matter. But the homeowner works at the level of the job: what was asked, what was done, and what proves it.

What you will learn. Where the work went when agents began writing the code, and why your attention moves from the file to the change itself.

Why it matters. Writing got cheap. What a team now lacks is the time to prove that a change is right.

Where did the work go?

To the steps around the code. A bottleneck is the slowest step in a process. It decides how fast everything else can go, the way the narrow neck of a bottle decides how fast the water pours.

When people wrote every line, writing was the bottleneck. A feature took days to type, test and fix, and review was a short step at the end. Coding agents changed that. Tanya's agent, in this chapter's opening story, wrote its change in twenty minutes. An agent can open more pull requests in a morning than a person can read in a day.

The work did not disappear. It moved:

1. Saying what you want. The outcome, what is not part of the job, and how you will know it is right. An agent builds what it understood, fast. A vague request now produces a large wrong change in minutes.
2. Proving it is right. Tests, types and checks that run on every change, and evidence instead of claims.
3. Judging what machines cannot. Review of intent, which is what the change is meant to do, of policy, and of what else the change touches.
4. Getting it into production safely. Merging, turning it on for a few users and then for everyone, with a way back at each stage.

Faster writing makes the line of waiting work at steps 2 to 4 longer, not shorter. More changes arrive, and each one still has to be proved, judged and shipped, which means delivered to its users. A team that skips these steps does not go faster. It ends the way Tanya's story did. The case study shows the other path. That team's merged pull requests more than doubled while its share of reverts fell, because it rebuilt how it proves its work is right, not how it writes.

Which two skills matter most now?

• Specifying intent. Saying clearly, before any code exists, what the change is for and what "correct" means. Chapter 12 taught you to brief an agent and check its plan. Chapter 21 turns that into full specifications.
• Validation and delivery. Proving that what came back is right, and taking it into production without breaking anything. Code that cannot be validated cannot be shipped, however fast it was written.

Step 1 above is the first skill. Steps 2 to 4 are the second. This chapter is about the second skill, and it shows how the first one helps it. A change brief, a short file kept in the repository (15.5), starts with intent. Tests written first (15.4) turn intent into checks a machine can run. Review rules, review by AI, required checks, approval and rollout (15.6 to 15.10) do the rest.

Figure 15.1. The bottleneck is shifting. Agents shrink the writing. Specifying intent, checking, reviewing and releasing become the slow steps that limit a team, and they are the skills this chapter builds. It shows the idea, not measured time.

What replaces the file at the center of my work?

The proposed change, a set of edits offered for acceptance, with its purpose and its evidence. For fifty years, a code editor has been organized around files. A developer opens a file, reads lines and types lines. When an agent writes most of the lines, your attention moves, and your questions change. Did the agent understand the request? Which assumptions did it make? What will change for the people who use the software? What could break? What is the reason to accept the result? Those questions are all about the proposed change.

So the unit of work, the one piece you judge and accept, becomes the proposed change, and the files stay one click away for when you need them. Nobody has built the editor for that work yet, and nobody knows what it will finally look like. But a pull request (Chapter 12 named it, and 15.3 explains each part) is the closest thing to that unit today. On one page it already holds the purpose of a change, the lines it changes, the steps it took, the discussion, the automated checks, and the decision to accept it. This chapter teaches you to use it as a place where a change is proposed, proved and decided, not only where code is read.

What does a pull request not hold yet?

Behavior, which is what the program does when it runs. A pull request shows diffs, lists of the lines that changed. Those lists do not say what the lines do to a payment run. So a good proposed change adds evidence. It says that under these inputs the program did this, here is the command and the output, and here is what is still uncertain.

What if the request is not clear yet?

Then the agent's first job is to investigate. Not every change starts with a clear request. Many start with a problem nobody understands yet, such as an export that shows the wrong total, or a report that runs slowly. The agent reproduces the problem, which means it makes the problem happen again. It separates confirmed findings from guesses, and asks the questions only a person can answer. Only then does the investigation become a proposal with clear limits. Keeping those stages apart stops a guess from turning into code nobody asked for.

What makes evidence trustworthy?

Four marks, or signs, make it trustworthy. A well-written summary can make weak evidence look strong. Evidence you can trust is:

1. Traceable and scoped. Traceable means it links to a real run with known inputs. Scoped means it says which outputs were checked. If it only assumes an output was not affected, it says so.
2. Sourced. Each expected result says where it came from: an agreed rule, a hand calculation, or an assumption waiting for an answer. If the same agent writes the code and its tests from one wrong reading, both agree and both are wrong.
3. Current. It belongs to one version of the code. New commits, which are new saved versions, make old evidence stale, or out of date, until the checks run again.
4. Explicit about acceptance. It says which decision is being accepted. Merging code, changing stored data, and turning a feature on are different decisions, with different ways to undo them (15.10).

How much evidence a change needs depends on what it could break. 15.5 sets the amount, from a one-line description for a typo, a small spelling mistake, to a short brief for a change that moves money.

Does it help if a second agent agrees?

Only if its checks can be read and run again. A second agent can challenge the first. But two agents agreeing proves nothing on its own.

At work. Ana Morales, the AP analyst, reads the weekend rule from Chapter 13 as a proposed change, not as a file. Its purpose: pay weekend due dates on the Friday before. Its claim: with the rule on, 10 invoices, $33,109.53, are due by Friday, March 5. Its open decision: whether AP uses the policy at all, which belongs to Dave Kowalski, the controller, not to the builder. She asks for the command that proves the claim, and for what else the rule touches. That second question points to the file where 15.7 finds a bug.

Why the change, and not the file?

Because proving the work is now the slow part, and you prove a change, not a file. You ask what it was for, what it did, and whether the evidence is still true. So the change is what your tools, and your attention, should be built around.

The operating rule: judge a change by its purpose, its evidence and what it could break, and open the files when the evidence points there.

Figure 15.2. The proposed change at the center. Intent, code, evidence, review and acceptance stay linked, so a changed requirement or new commits show which evidence is now stale.

Practice it. Practice: the proposed change, in your own tool, fifteen minutes, and a few more the first time, for the setup.