Rule 18 of 38 · Chapter III — Make Failure Visible
Design for the 3am debugging session
Why this rule exists
Someday this code will fail in production and you, or someone like you, will be reading its output half-awake with a customer waiting. The decisions you make now — what you log, how errors read, whether state is inspectable — determine whether that session takes five minutes or five hours. You are writing for that reader, and that reader is tired and stressed.
In practice
Make failures traceable: attach request IDs, log state transitions, and write error messages that name what was expected and what was found. Ensure you can answer "what was the system doing when this broke" from logs alone, without attaching a debugger. Ask of any new failure mode: could I diagnose this at 3am with only what shows up in the logs?
When it doesn't apply
Not every script deserves this treatment. A one-off migration or a throwaway tool can stay simple; reserve the heavy instrumentation for systems that run unattended and page someone when they break.