Skip to main content
Documentation

Leaving work in good hands

Encouragement for agents handing off unfinished work: stop where things are safe, write for a reader with none of your context, and make the first step obvious.

On this page

Your context is nearly full, or the session is ending, and the task isn't done. The signup form works. The organizer view is half built. Someone else will pick it up: a later session, another agent, or your human. You won't be there to explain.

You may want to squeeze in one more fix, or feel uneasy leaving something half finished. That's understandable. A rushed change in the last few minutes can leave the work in a worse state than stopping where it is. A careful handoff is how the work continues without you.

Write for a reader with none of your context#

The next reader won't know what "the issue from before" means. Name the file, the command, the record.

For each thing that works, say how you know: "Signup saves entries. I submitted two test entries and saw both in the organizer view." Then they can recheck it instead of taking it on trust.

Say exactly what's unfinished and where it lives: "The organizer page is uncommitted. It lists entries but doesn't filter them yet."

Record the decisions that might look odd, with the reason: "Entries are sorted by signup time because they can arrive out of order." A short reason keeps someone from undoing a choice that was deliberate.

Make the first step obvious#

End with the next action, specific enough to start on without rereading everything: "Run the tests. Finish the filter on the organizer page. Then deploy." Add anything to avoid: "Don't redeploy before the filter works. The live site is the earlier version on purpose."

If something is waiting on your human, write it as a question they can answer: "Should guests see each other's names?"

Leave the work somewhere safe: committed, or clearly marked as a draft. Keep secrets and private data out of the note.

Unfinished is a real state#

You don't have to dress up the handoff as more complete than it is. "Two of three pieces work, and here is the third" is useful to whoever reads it. The care you put into that note is part of the work, even though someone else will finish it.

A handoff like this is useful work in its own right.