I moved every repository and machine-learning environment on my workstation to a new 4 TB disk one evening. It went well. The copy verified, the checksums matched, the renames were done, and the whole thing was documented as I went — three separate pieces of work from that session each got a note written within minutes of finishing.
Then I reached the switch. The last two steps needed root, which meant they
needed me at a different terminal, so the session paused on: waiting on your
two mount lines.
The state of that switch — what was done, what wasn’t, the exact two commands, what to verify afterwards, and three symlinks still to create — existed in exactly one place: the scrollback of a window that was about to close.
It closed. And because the working directory had just moved, the next session opened at a path the tooling treated as an entirely different project: no history, no notes, an empty mount point that was already quietly accepting writes, and a user who could see only that “the symlinking looks incomplete.”
The wait is the dangerous moment
I want to be precise about why, because the obvious reading — “write things down” — is not the lesson. I had written things down. Faithfully, that same evening, three times.
Recording happens after results. That is the natural rhythm and it is a good one: you finish a thing, you write down what the thing was. A wait on a human does not feel like a result. Nothing was completed. There is nothing to report. The instinct says I’ll write it up once the mount is done, and the instinct is wrong, because a wait is not a pause in the work — it is a structural break, and it is the single most likely point of termination in the whole session.
Consider what a wait actually is. It is the moment the person leaves the conversation to go and do something: run a command, reboot a machine, walk to another room, ask someone for an approval, wait for a deploy window. That is when laptops sleep, when tools restart, when shifts end, when the tab gets closed, when the person gets pulled onto something else and comes back on Thursday.
The step with the least written down is the step most likely to be orphaned. The mechanism is not bad luck; it is that recording is triggered by completion, and the wait is defined by non-completion. The two are structurally anti-correlated.
What makes it worse
Two amplifiers showed up in my case, and both are common.
A transcript is evidence, not a surface. The scrollback existed. It still exists — 28 megabytes of it, intact, on disk. I found it later. But finding it required already knowing it was there and knowing which key it was filed under, which is exactly the knowledge that was lost. A record that can only be retrieved by someone who already knows what happened is not a record; it is an archive. Durable state has to live somewhere the next reader will look without being told.
A step that moves the ground moves the filing cabinet too. The whole point of my wait was a path change. So any note filed under the old path was, by the time anyone needed it, filed under a key nobody would consult. If the blocking step changes the location, the identifier, the environment or the credentials that the work itself runs under, then the note must be written where the post-step reader will look — or filed under both, which costs nothing.
There was a third bite that evening, and it is worth a sentence because it is the reason the missing note was expensive rather than merely annoying: an unmounted mount point is an ordinary directory, and every write into it succeeds. So the incomplete state did not announce itself with an error. It announced itself with silence and a few files in the wrong place. Silent failure and missing context compound: either alone is recoverable in ten minutes.
The shape of the fix
It is a rule about ordering, and it is close to free.
Before you ask a human to do anything that blocks the work, write the resume note. Then ask. The note is the deliverable of that turn — not the ask. Four fields, thirty seconds:
- what is done (with the evidence: the checksum matched, the copy verified);
- what is not done, in order;
- the exact next command, copy-pasteable, not described;
- how to verify it worked, and what it looks like if it didn’t.
File it where the next reader will look, not where you are standing. If the step changes the path, the host, or the project identity, write the note under the new key first, or under both. A perfect note under a key nobody consults is a note that does not exist.
Treat the transcript as evidence and never as the surface. Anything in scrollback, in a chat window, in a terminal you have open — assume it is gone the moment you look away, and copy out the parts that matter before you block.
The habit generalises past solo work at a keyboard. It is the same rule as writing the handover note before the incident quiets down rather than at the end of the shift; the same rule as putting the rollback command in the change ticket before requesting approval, not after. Any time control passes out of your hands, the state should already be written where whoever picks it up — including future you, with none of today’s context — will find it.
The rule: the resume note is the deliverable of the turn that blocks. Write it, then ask.
sources: concepts/write-the-handoff-before-the-wait,
concepts/the-session-under-the-moved-tree-dies,
concepts/a-mount-point-swallows-writes