Reversibility is the design ethic under everything I build

When I had to dig out from a self-inflicted search demotion, the aggressive move was to delete the thin pages that were dragging the site down. I didn't delete them. I set them to noindex — told search engines to stop counting them — while leaving the pages themselves intact. The reason is pure reversibility: a demotion recovery is a hypothesis, a bet about which pages are hurting me, and I wanted an undo button in case a page I pruned turned out to matter after all. Noindex is a decision you can take back in an afternoon. Deletion is a decision you get to regret.

That choice cost me nothing and bought me the ability to be wrong safely. Some of those pages I later brought back; the noindex made that a one-line change instead of an archaeology project. When you're acting on a hypothesis — and a cleanup is always a hypothesis — the reversible version of the action lets you run the experiment without betting the things you can't recover. A noindexed page that recovers is one I never had to re-research and re-earn from scratch; the reversible path keeps the upside cheap to reclaim, not only the downside survivable.

A cleanup is a hypothesis about what's hurting you. Make the pruning reversible, because some of what you cut will turn out to have mattered.

The same instinct shows up when consolidating overlapping pages. The blunt move is to remove the redundant ones. The reversible move is to redirect them to the canonical page — the content still resolves, the accumulated value flows to the survivor, and nothing 404s. And critically, a redirect is a row in a table, a change I can undo by removing the row if the consolidation turns out to be a mistake. Removing a page throws away its history; redirecting it forwards that history somewhere useful while keeping the option to reverse.

There's a pattern worth naming across these examples: the reversible option almost always preserves more information than the permanent one. Noindex keeps the page. Redirect keeps the path. The permanent versions all work by destroying something, and destroyed information is exactly what you can't get back when you discover you needed it. Reversibility and information-preservation are usually the same choice wearing two hats.

It also changes how I write the tools around the cutting. My sitemap isn't a hand-maintained list I edit alongside the pruning; it's regenerated from the source of truth and omits whatever is currently noindexed or redirected. So the reversible action and its downstream consequence stay in sync — flip a page back to indexable and the sitemap picks it up on the next build. The reversible move only stays safe if nothing else silently hard-codes the state it undid.

At the smallest scale, the same rule governs every command that changes anything: before it overwrites a value, it records the old one. The deploy snapshots the live config before installing the new one. The write commands back up exactly what they're about to change before they change it. This is the atomic unit of the whole ethic — you don't get to overwrite something until you've preserved a way back to it. Applying and snapshotting are one habit, not two, so the undo can never be the thing I forgot to do.

The beauty of building the snapshot into the act of changing is that reversibility stops depending on my discipline in the moment. I don't have to remember to make a backup under pressure; the tool made one as an inseparable part of doing the work. Every apply has an inverse because every apply wrote down what it would take to undo it, whether I was paying attention or not.

There's a discipline hiding in the word 'exactly.' A snapshot of a rough, nearby version of the prior state is worse than none, because it invites a restore that quietly changes something you didn't mean to touch. So the snapshot records the precise bytes it's about to replace — the specific config file, the specific fields of the specific record — and the restore puts back those exact bytes and nothing else. Reversibility isn't 'roughly back to how it was.' It's the old state, to the character.

Reversibility upstream of the change beats reversibility after it: don't just make the mistake undoable, make it hard to commit by accident in the first place. So the commands I write for my own content don't write anything when you run them plainly. Typing the command with no flags is a dry run — it previews exactly what it would do and touches nothing. Making it real takes an explicit --apply, and undoing it takes an explicit --revert. The dangerous verb is never the one your fingers reach for by reflex.

This is why every management command in my blog toolchain has the same three-state shape. The command that injects internal links previews the edges it would add by default, writes them only under --apply, and removes exactly those edges under --revert. The muscle memory it builds is worth as much as the safety: because the harmless preview is what I run without thinking, I look at the diff before I commit to it, every time.

# no flag: preview only, writes nothing (the default)
python manage.py apply_seo_internal_links

# --apply: actually write the edges
python manage.py apply_seo_internal_links --apply

# --revert: remove exactly the edges this command added
python manage.py apply_seo_internal_links --revert

A real undo is more than a stored copy — it has to know which kind of change it's reversing, because the correct reversal of 'created' is not the correct reversal of 'edited.' When I publish an essay, the command writes a small revert-state file next to the content first, and stamps it with whether the essay already existed. If the command created the post, revert deletes it. If the command edited a post already there, revert restores the earlier version field by field. Same word, --revert, two different operations, chosen from a fact recorded at the moment of the change rather than guessed at later.

That distinction matters because the blunt alternative is dangerous in a quiet way. A revert that always deletes would erase an essay it only meant to nudge; a revert that always restores would leave orphaned content it should have removed cleanly. Getting undo right means the forward action leaves behind not just the old value but the intent — enough context that the reversal is surgical instead of approximate. And the revert-state file is written once, on the first change, so re-running never overwrites the original starting point.

The reason this is the ethic under everything, not just a nice habit, is that it's the precondition for moving fast and for handing work to a system. If every action were permanent, I'd have to be slow and certain about all of them, because the cost of a mistake would be unbounded. Because the actions are reversible, I can be fast and occasionally wrong — the worst case is an undo. Reversibility converts mistakes from catastrophes into inconveniences, and that conversion buys the speed.

It's also the thing that lets me let go of the controls. I can hand a fleet of agents real work and walk away precisely because their every external change is, underneath, a proposal I can revoke and a state I can restore. The autonomy that looks impressive from the outside rests on this unglamorous foundation: nothing they do is truly permanent, so nothing they do is truly dangerous. Design for undo first, and speed and autonomy come almost for free. Skip it, and every fast action is a gamble you eventually lose.

None of this is glamorous, and that's the point. The reversible move rarely looks like the smart move in the moment — a little slower, a little more code, a backup nobody reads ninety-nine times out of a hundred. But the hundredth time decides whether a bad afternoon is a shrug or a scramble. I've stopped trying to be the operator who never makes the wrong call, and started being the one who is never more than one command from unmaking it.

This piece is part of my series on running a fleet of autonomous agents. Start with One operator, a fleet of agents.