Most error messages are written for the wrong reader.
They're written for the person who's watching when the thing breaks. You're at the terminal, the run fails, the message says connection refused or validation failed at step 3, and that's enough, because you have all the context in your head right now. You know what you were doing, what you changed, what the system was supposed to do. The message just has to jog a memory you already have.
The reader who actually needs the error state is someone else entirely, and they show up months later. I got talked into this view in a long comment thread on an earlier post, and it changed how I think about failure handling, especially for the async, agent-driven work I do a lot of now.
The reader you're not designing for
Here's the gap. When an interactive tool fails, there's a human in the loop who reacts immediately. The error can be terse because the context is live. You scroll up, you see the conversation, you fix it.
Async work has none of that. An agent runs a pipeline at 2am, something fails partway, and nobody sees it land. There's no conversation to scroll back through, no replay button, no warm context in anyone's head. Whoever investigates shows up cold, hours or weeks later, and the only thing they have is whatever the process wrote down before it stopped.
Which means, for that reader, the error state isn't a report about the failure. It is the failure, as far as they can ever see. If the record doesn't contain what they need to reconstruct what happened, the information is gone. Not hard to find. Gone.
That reframes the whole design question. It stops being "how do we format this error" and becomes "what does an investigator need to rebuild this run from nothing." Those are different specs, and almost every error message I've ever written was quietly answering the first one.
A message versus a record
The cleanest way I can put the distinction: most errors are a message, and what async work needs is a record.
A message is written for someone who shares your context. It can be short because it's pointing at things you both already know. "Validation failed" is a fine message when you're standing right there.
A record is written for someone who has nothing. It has to carry the context with it, because there's no shared memory to lean on. What was the input. What stage was this. What did the system believe was true when it decided to proceed. What got retried, how many times, with what result. A record is heavier on purpose, because its whole job is to survive the gap between the failure and the person who reads about it.
The test I use now: if I deleted the rest of the system and handed someone only this error state, could they tell me what went wrong? If the answer depends on context that lives anywhere other than the record itself, I'm writing a message and calling it a record.
The gap is also where organizations forget
There's a second reason the later reader has nothing, and it's not just time. It's people.
The person who built the system often isn't the person debugging it three months on. They've moved teams, moved companies, or just moved on to other work and dumped the context. So the investigator isn't even future-you, who at least shared your assumptions once. It's a stranger who was never in the room when the decisions got made.
That's the strongest version of the spec, and the most honest one. You're not writing for yourself later. You're writing for someone who has none of your context and never did, and who is meeting your system for the first time through its failure. If the error state only makes sense to someone who already understands the system, it's useless to exactly the person most likely to be reading it.
What this changes in practice
I haven't rebuilt everything. But a few habits shifted, and they're cheap.
I write error states as if the reader has no access to the rest of the run. Not "step 3 failed" but what step 3 was trying to do, what it received, and what it expected. The extra sentence costs nothing now and saves an hour later.
I treat the clean error state as the audit trail I'm choosing to have, rather than a thing I bolt on if there's time. In async work there's no other trail. Either the failure left evidence or it didn't, and that's decided when I write the handler, not when the incident happens.
And I stopped optimizing failure output for the demo. The version that looks good when you're watching it succeed is not the version that helps when it fails unattended. Those are different audiences, and the unattended one is the one that actually needs help.
The smallest version of the idea
If I compress all of it into one line, it's this: useful right now and useful in three months are different specs, and you usually only get to satisfy one of them, so pick the harder reader.
Pick the stranger. Write the record they'd need, not the message you'd understand. You won't be in the room when it's read, and the whole point of an error state is to work when you're not there.
I build WordPress plugins and write about AI tooling and security at https://raplsworks.com/.
Disclaimer: The experiences and decisions in this post are my own. English isn't my first language, so I use an AI assistant to help draft and edit the writing.
Top comments (12)
"Write for a reader with no other access" — this is the same blind spot from the QA side. Someone ships a 97% coverage report generated in a clean sandbox. Three months later production breaks and nobody can debug it because the only record says "all green." The error state was perfect — for the wrong environment. Followed you 👀
"Perfect for the wrong environment" is the QA version of the exact trap, and it might be the cleanest example of it I've seen. A 97% coverage report isn't a record of what the system does, it's a record of what the sandbox did. It reads as reassurance and contains nothing the production debugger actually needs. "All green" is the worst kind of error state: it's confident, it's complete-looking, and it answers a question nobody will be asking in three months.
The shared root is that both were written for the environment they were born in, not the one they'd be read in. A clean-room green and a terse "failed at step 3" fail the same way, by assuming the reader shares the context the author had at write time. The fix is the same too: write down what a stranger in a different environment would need to reconstruct the run, not what looked true in the room where it passed. Appreciate the follow, and the QA angle, that's the half I don't see from where I sit.
Same axis, your second angle on it. "Useful right now and useful in three months are different specs" generalizes beyond error states — it's the whole job of operator discipline.
A decision is a message in the session where it happens. It becomes a record only when you write it down as state with a status field. Recaps written for yourself drift; live captures written for a stranger don't.
Yeah, the status field is the load-bearing part. One thing I'd add from getting burned: a live capture only beats a recap while someone keeps flipping that field. A status nobody updates when the decision gets reversed lies more confidently than any recap, because it still reads as a record. So the discipline isn't only writing the decision down as state, it's owning the state after the decision moves. Same spec, just a longer tail than I first thought.
Exactly the tail I'd been calling it wrong about too. Status that stops getting flipped is worse than no record — it codifies a lie as ground truth. The fix I landed on is making the state machine carry the ownership, not the operator: every decision has a lifecycle (proposed → accepted → locked → rejected → superseded), and a drift detector that fires when a new prompt contradicts a locked one. The human still owns the transition, but the machine refuses to let it sit stale silently. „Same spec, longer tail" is the right frame — and the tail is where the discipline becomes a system, not a habit.
The drift detector firing on contradiction is the piece I hadn't pinned down. That's the line from habit to system. Good thread.
Your "status field load-bearing" three rounds ago was the seed — drift detector is just that point with enforcement attached. "Habit → system" is the cleaner frame for the whole shape; keeping it. Likewise.
I started treating errors like incident reports, not messages. What broke, what it saw, what it tried, what it assumed. It’s a bit more verbose, but debugging later becomes way less guesswork.
Incident report over message is exactly the shift. Of your four, "what it assumed" is the one I'd underline. It's the highest-value field and the first to get dropped, because at the moment of the break the assumption feels too obvious to write down. Three months later that's the only line you can't reconstruct. The verbosity buys you the one thing your future self physically cannot reverse-engineer from the stack trace.
I ended up turning it into a small reference I use daily (not a tool, just my own debugging brain‑dump): debug.visionvix.dev/
It’s wild how much easier debugging becomes when you write for the stranger you’ll be in three months.
This aligns closely with what I’ve been optimizing for in production systems—treating error states as first-class domain artifacts rather than incidental byproducts of control flow.
One pattern that has worked well is enforcing structured error contracts at system boundaries, e.g.:
consistent error typing (domain vs infrastructure vs validation)
stable error codes instead of free-form messages
contextual metadata injection (request_id, trace_id, entity_id)
It dramatically improves debuggability in distributed systems where logs are the only source of truth after the fact.
I also try to avoid “human-optimized” error messages in core logs. Instead, I log machine-stable signals and layer human-readable context at the presentation boundary (API gateway / UI layer). This prevents semantic drift when systems evolve.
Another underrated practice is treating logs as an event stream, not a debug dump—so every error state should be replayable in terms of system state transitions, not just stack traces.
In hindsight debugging scenarios, the biggest win has been enforcing invariant-style logging: if a function can fail, it must emit enough deterministic context to reconstruct pre-failure state without relying on developer memory.
That “write for a stranger in 3 months” framing essentially pushes you toward better observability design—structured logging, traceability, and reproducibility rather than ad-hoc debugging.
Structured error contracts at the boundary is the right backbone for this, and the one I'd single out is your point about not putting human-optimized messages in core logs. On the surface it reads like the opposite of "write for a stranger in three months," and I think the resolution is that they aim at different layers. The core log should be machine-stable: typed, coded, carrying request_id and trace_id, precisely so it survives the system evolving. The "stranger in three months" part was never the wording, it's the context payload, the what-it-assumed and what-state-it-was-in that lets someone rebuild the failure without your memory. So machine-stable signal and human-reconstructable context aren't in tension, they're two fields in one record: one stays stable for the parser, the other stays legible for the person. The drift you're avoiding comes from putting prose where a code should be, not from carrying enough state to replay it. Invariant-style logging is the cleanest version of that, and the stranger and the parser both win.