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,...
For further actions, you may consider blocking this person and/or reporting abuse
"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.