Why I write things down before I automate them

Every automation that's gone badly started the same way: skipping straight from ‘I do this thing manually’ to ‘let's automate it’, without ever writing down what the thing actually is. It feels like the fast path. It's usually the slow one.

Writing it down first forces a specific kind of honesty. The manual version of a task has a dozen small judgement calls baked into it that never get named because a person just handles them in the moment — what counts as done, what to do when the input looks slightly wrong, which edge case actually matters versus which one is rare enough to ignore. An automation can't make those calls invisibly. It needs them written down somewhere, and the cheapest place to write them down is before any code exists, not after something's already misbehaving in production.

The other thing writing it down catches: tasks that don't actually need automating at all. A few times now, getting three sentences into ‘here's what this process does’ has been enough to notice the process itself is the problem, not the manual effort — automating a bad process just makes it fail faster and more consistently.

The rule I've settled on: if I can't explain a task clearly enough that someone else could follow the explanation and get the same result, it's not ready to automate yet. That's not a formal spec, just a plain-English paragraph. Cheap to write, and it catches most of the expensive mistakes before they're expensive.