Working with AI is a handover problem

Working with an AI is like working with a super-genius intern with dementia. Immensely capable, and holding almost none of the context the job needs. You cannot expect them to read your mind, and you cannot expect what you told them last week to still be there.

The line is memorable and it is worth keeping. It is also wrong in a way that changes what you should build, so it is worth correcting immediately.

It is not forgetting. It is never having known.

Dementia is the degradation of a memory that was there. An agent never had one. Every session begins from nothing, reconstructing from whatever is in front of it.

That distinction sounds pedantic until you notice it changes the fix. Forgetting is solved by reminding. Never-having-known is solved by a handover — and a handover is the harder of the two, because a reminder can assume shared context and a handover cannot assume any.

The metaphor breaks in two more places, and both are load-bearing.

An intern learns. Six months in they need less context than they did on day one. This is why teams that document badly get away with it: the intern accumulates what the documents never said, and the gap closes on its own. An agent never accumulates. The twentieth session needs the same brief as the first, and will need it again next month.

That is the argument for treating written context as infrastructure rather than courtesy: you cannot amortise sloppiness against someone who is new every time.

An intern asks. Told “come and find me if you’re unsure”, they will. An agent under-asks, and does it confidently — filling a gap with the most plausible reconstruction rather than stopping. That is not a flaw to be scolded out of it; it is a property to design around, and it is why the stop-and-ask boundary has to be written down explicitly rather than left to instinct.

What follows

If every session starts cold, four things stop being optional.

Context has to be written, not remembered. Anything held only in your head is unavailable to the work. The test is uncomfortable and clarifying: if you were unreachable for a fortnight, what would somebody need in order to continue? That is the corpus.

It has to be findable without knowing it exists. An agent cannot search for a constraint it has no reason to suspect. Structure and naming are not tidiness — they are the difference between a document that gets read and one that does not.

It has to say where to stop. Capability without a boundary produces confident action in exactly the places that need a pause. The boundary is the part nobody can infer.

It has to survive being extracted. These files get dropped into repositories and read by agents that never see where they came from. Anything true only in the original context is lost on arrival.

The four layers

Each answers a different question, and they are separable — adopting one is useful, and adopting all four compounds.

1. Rootnotes — what cannot be discovered

Documents at the project root carrying what the repository cannot state: the commercial facts, the conventions, the constraints somebody decided once, and the points at which an agent should stop and ask.

The test for whether something belongs here is whether an agent sitting in the repository could work it out. A framework is discoverable. A jurisdiction is not. A file-naming scheme is a choice nobody wrote down.

2. The documentation set — what was decided, and why

A linked set rather than a pile or one long file: about, architecture, features, decisions, tests, runbook, roadmap. One file per section so a narrow task loads a narrow slice, and links between them so a stale claim shows up as a broken relationship rather than a paragraph nobody reads.

The decision log is the highest-value part and the cheapest to write. The alternatives you rejected are clear exactly once — while you are rejecting them.

3. The working agreement — how work happens, and where it stops

What may be run unattended, what stops for a human, what an honest report looks like. The prohibitions matter less than one property: an agent’s report is not verification, and a reader should be able to predict what they will find when they look.

The tempo of that changes with how you work. A human present turn by turn makes asking cost seconds; a review gate makes it cost a day; unattended, there is nobody to ask and the correct move is to stop rather than to choose. Same boundaries, different cost of pausing.

4. A retrieval corpus — what is too large to hold

Beyond a certain size, context cannot be loaded; it has to be fetched. Reference material, prior decisions, transcripts, specifications. The design question is not which store to use but what a good answer looks like when the agent does not know what it is missing — which is a problem of chunking and naming far more than of embeddings.

A fifth layer, and why it is separate

The four above are behavioural: they change what an agent does. There is a fifth that is different in kind — measurement. Does any of this actually hold? Are the documents current? Was the rollback ever run? Is the standard being followed or merely present?

It is separate for a reason worth stating plainly. The behavioural layers are most of the value, and they require no tooling at all. A reader who adopts the rootnotes and installs nothing gets most of what is on offer here. Measurement tells you whether a system is holding; it does not create one.

It also carries a specific hazard, and anyone building it should know this before they start: a tool that measures your system can be confidently wrong, and its interface will not say so. A scanner’s own source necessarily contains every token it searches for, so a document about a convention reads as a document following it. That failure is invisible to a test written by whoever wrote the check, because both share an assumption.

The instinct when a scanner disagrees with you is to trust the scanner. That instinct is frequently wrong, and a half-built measurement layer with an authoritative interface is worse than none.

What we can and cannot claim for this

We use this. The documents on this site are the artefacts it produces, which is the strongest evidence available for it and is still weaker than a controlled comparison — there isn’t one, and we are not going to pretend otherwise.

One observation is worth reporting precisely because it is small and specific. A convention was placed in a documentation standard in one project. Seven hours later, an agent in a different project — different repository, different task, nobody asking — had adopted it. That is one data point, and it is offered as one: not proof that structure changes behaviour, but the reason we think it is worth your time to find out.

Where to start

Not with all of it.

Write one decision record, today, for something you decided this week. It is short, it is the highest-value form, and it is the one nobody regrets.

Then one rootnote, for whichever thing you have most often explained twice.

The rest follows from noticing how often you stop repeating yourself.