What the next agent needs to know

Our agents can produce code faster than I can review it. That makes the handoff consequential: a new agent may be able to change the implementation without knowing which parts of the experience it must preserve.

One playback bug made the distinction concrete. In an app for listening to recorded conversations, tapping a sentence sometimes played a different passage by the same speaker. The app knew who had been selected, but not which sentence. Correcting that behavior was only part of the work. A separate reviewer caught an old layout wrapper squeezing the new playback slider. Its finding, the correction and the checks stayed together, instead of disappearing into another conversation.

I want the next agent to inherit that reasoning—not just the finished code or a reassuring “done.” We keep it in a track: a bounded piece of work with its specification, plan, reviews and evidence beside it. A playbook describes how that work moves between steps. The lesson does not require adopting our whole playbook; one well-defined handoff is enough to try it.

Reconstructed from the saved review—not a UI capture or evidence of automatic dispatch.

Give the work an address

The playback track’s specification recorded the intended experience. “Fix playback” would have left too much to guess: hearing the right speaker is not the same as hearing the passage the person tapped.

The plan described the correction: carry the selected turn’s start and end times into the speaker-labeling panel, where a sample helps the person identify the speaker. But it also preserved a distinction a fresh implementer could easily miss. When someone arrived without selecting a particular passage, playing that speaker’s longest utterance was still the intended fallback. The fix needed to change one path without erasing the other.

That is useful context to hand over. A specification says what experience to preserve; a plan proposes how to build it. Keeping them beside the work lets another agent inspect the relationship—and notice when a seemingly tidy simplification would remove behavior we still want.

The playbook gives the next step a job

Once the reason for a change is written down, the next question is what to do with it. Writing a plan, implementing it and reviewing the result are different jobs. Our playbook gives each a place in the lifecycle, an expected output and a route back when a review finds something that needs revision.

Reviews are part of the route, not optional checks beside it; optional phases, amendments and exit routes are omitted.

The coordinating program records step entries and transitions separately from the documents agents produce. On resume, it uses those records to determine the current job and supply its instructions. A reviewer receives the artifact to review; planning can receive unresolved findings explicitly carried forward from specification review. The agent does not have to infer its assignment from where a conversation happened to stop.

This describes the version behind the archived work, not a claim that every track followed it perfectly. The program checks which transitions are permitted; instructions tell agents to address findings and verify the result. Advancing the workflow does not independently rerun every check. A valid transition tells us that the work moved, not that it met the intended outcome.

A fresh review can be narrower than a whole conversation

The playback plan called for an adversarial review by an agent starting in a fresh context. Its review names the material it received: the full diff, four target files, the existing playback function, build configuration and test wiring. That is a specific starting point rather than an instruction to reread the entire project conversation.

The reviewer noticed a problem outside the audio logic. The new playback row contained a Stop button, a slider and an elapsed-time label, but an old layout wrapper still reserved empty space beside it. That space competed with the slider and squeezed it. The correction removed the outer wrapper and spacer so the playback row could use the available width.

The landed code confirms that change. The review records a rebuild and three passing UI proof tests, and a saved screenshot shows the corrected controls. Those tests checked that the slider, Stop button and time label existed—not the slider’s width. The source change and screenshot are the evidence for the layout correction; a green test result alone would not establish it.

The saved review makes that chain available to a successor: the behavior questioned, the reason for changing it, the correction and the limits of the check. A short assignment that omits a necessary constraint is not an efficient handoff; references let a worker retrieve more when the job demands it.

The coordinating interface supplies a packet describing the current step, its intent, expected output, context and next action. Choosing an agent to perform it is a separate responsibility. We found no automatic child-agent launcher in the inspected lifecycle code, even though this particular review documents a fresh-context subagent.¹

Historical runner contract illustrated by one documented playback review; the observed folder lacks some lifecycle records, and child-agent dispatch is not automatic in the inspected runner.

Open the handoff illustration at full size. The durable folder stays with the work; the smaller assignment tells a worker where to begin and where to return its result.

The aim is to avoid replaying a whole conversation when the job needs a few relevant sources. We have not measured context-volume, cached-input or total-cost savings, and those are separate quantities. The benefit this record establishes is more modest: we can recover what the reviewer was asked to inspect and what followed its findings.

Keep the proof close enough to question

Retaining an artifact does not make it evidence for every claim. In the playback track, the saved simulator assertions answer the original selected-passage question: an early-line test expected 0–8.2 seconds and rejected a later interval at 17.9–27.8 seconds. Those assertions concern which passage was selected, not how interruptions or layout behaved.

Drawn from saved post-fix test assertions, not a recorded waveform or before-and-after screenshot.

The screenshots gave interface context, but the two sample screenshots were identical. Their pixels could not establish that different passages played. A successor needs to know what a check proves, not merely that a folder called proof exists.

The record also contradicted itself. The track’s status still said “reviewing” after the correction had merged, and some of the separate review and transition records were missing. Comparing the label with the merged change, review and proof exposed that disagreement. Keeping history made the problem inspectable; it did not remove the work of reconciling it.

The method itself needs review

Sometimes the thing we need to question is not the change but the way we judge it. Our agents write specifications describing what to build and plans describing how to build it. Both get reviewed. When an AI evaluator scored those reviews, two planning reviews we considered good received just 2 out of 10.

The retained examples and criteria exposed a mismatch. A specification review should ask whether the proposed acceptance criteria are clear and faithful to the intended change. A planning review should ask whether the proposed tasks cover that specification and are feasible in the codebase. We had judged planning reviews using specification-review criteria: they were being asked to evaluate a different kind of work.

In a small calibration, one specification review and two planning reviews scored 8, 2 and 2 under specification criteria. With criteria matched to review type, and shared examples anchoring what good review looked like, they scored 8, 5 and 8.

The measuring instrument changed; these are calibration scores, not a before-and-after measure of product quality.

Higher scores alone would not prove improvement. The reviewed work had not changed. We had changed the instrument used to judge it, and could explain why. Whether better reviews produced better software would require following their findings into the resulting changes and people’s experience of them.

That is another reason to keep the history: it lets us challenge the method before asking agents to optimize against it.

Try a handoff you can inspect

You do not need a state machine to try this. Use a plain file or an issue for one piece of work, and hand one step to a fresh agent. Here is a compact assignment reconstructed from the playback case—not the original prompt. Replace the source references with links or paths in your project.

Job: Review the playback change; identify regressions before it is accepted.

Intended outcome: Tapping a sentence plays that sentence’s time window, not another passage by the same speaker.

Constraint to preserve: When no particular passage was selected, the longest-utterance fallback remains valid.

Read: The specification and plan; the diff and affected files; the existing playback function; the relevant build and test setup. Ask for missing references instead of assuming what they contain.

Check: Does the selected entry path preserve start/end times? Does the unselected path retain its fallback? Inspect interruption and playback-control behavior as well. Record each as pass, fail or unverified, with evidence appropriate to that claim; distinguish inspected code from tests actually run.

Return: A review record linking each finding to the behavior at risk, proposed correction and supporting check. Carry unresolved findings forward. Return it to the person or agent coordinating the change; do not treat a completed review as permission to merge.

Then inspect the returned work. Could the agent identify the job without reconstructing the conversation? Did it retain the constraint? Could the next worker act on its findings? Record what a person still had to explain or correct, including failed attempts.

If the handoff fails, repair the missing context before adding more machinery. If you want to adopt additional review steps, compare similar tasks for repeated explanation, missed constraints and human correction effort. Keep the steps that earn their cost; these are proposed checks, not benefits we have already measured.

The next agent may find a better way to build the player. It should know both why tapping a sentence must play that passage and why the longest-utterance fallback still belongs elsewhere. Then it can change the implementation without unknowingly changing the experience—and leave the next agent a record of what it learned.