$ cat choices/write-it-down.md
the call
I get the map out of people's heads, on purpose. Architecture decision records, runbooks, written intent. The cross-system context that lives in one senior engineer's skull is the org's biggest risk and its most valuable asset. Externalize it and you survive losing anyone, and in the agentic era it's the difference between a fleet that has the map and one confidently building the wrong thing.
By default the map lives in a head, not a repository, and a head is a bus-factor-of-one dressed up as seniority. Writing it down converts tacit knowledge into a shared, durable, reviewable asset: decision records that capture the why (not just the what), runbooks for the 2am path, written intent for the thing that looks wrong but isn’t. It’s always been the highest-leverage move for surviving a departure.
In the agentic era it stopped being hygiene and became infrastructure. An agent can only act on what’s written down. A spec, a decision record, an intent doc is the interface you direct a fleet through. The tribal knowledge that used to live in standups and Slack threads is simply invisible to a fleet; if it isn’t on disk, it doesn’t exist as far as the agents are concerned. The map on disk is the line between a fleet that builds the right thing and one that builds the wrong thing beautifully, at scale. Writing it down went from a senior engineer’s good habit to the single highest-leverage thing a team can do to make agents worth pointing at the problem.
This is not a mandate to document everything. A doc nobody reads or maintains is worse than none, because it lies as it drifts and you trust it anyway. I don’t write down the obvious or the ephemeral. I write down the expensive-to-reconstruct: why a non-obvious decision was made, what bites at 2am, the context that would cost a week to rediscover. Living docs over comprehensive-and-stale, every time. The goal is the few things that matter, kept true. Not volume.
This is step one of the whole agent-era playbook, and I mean it literally: get the map out of people’s heads before you need to. I learned it the hard way being the load-bearing wall. When the cross-system context is in your skull, you’re not indispensable, you’re a single point of failure with good PR. The fix is to externalize the map so the org survives losing you. And the same written context is what an agent fleet reads to be useful, which is exactly why a monorepo matters: one legible place the map can live.— see: writing / Volume Is Free Now
The most durable thing a senior engineer ships isn’t code, it’s understanding. And understanding only survives if it’s written down where someone (or something) else can find it. Build the map outside your own head before the day you’re not there to consult. Knowledge that lives in one place dies in one place.
the gaps — what it costs even when it’s right
Docs rot, and a stale doc lies with confidence. Out-of-date written intent is worse than none, because people trust it. Either it’s a living artifact with an owner, or it becomes a trap; there’s no set-and-forget.
It competes with shipping for the same hours. Writing it down is real work that doesn’t look like output, so it’s the first thing cut under pressure. Which is exactly when the map matters most. You have to fund it on purpose.
Over-documentation buries the signal. A wiki of a thousand pages nobody can navigate is its own failure. The skill is writing the few load-bearing things well, not everything exhaustively.