| name | error-message-quality |
| description | Write errors and log lines that name the failing thing, the offending value, and the likely fix — for the 3am reader. Use whenever writing a throw/raise, a log statement, a validation message, or a CLI/API error response. |
error-message-quality
Every error message is read at the worst possible moment by someone with no context. Write for that reader:
- Three parts: what failed, with what value, what to do.
"config error: 'timeout' must be a positive integer, got '-5' in deploy.yaml" beats "invalid config" by an hour of someone's debugging. Include the identifiers: which file, which record ID, which endpoint, which of the twelve retries.
- Never swallow the cause. When catching and re-raising or wrapping, chain the original (
raise X from e, %w, cause); when logging-and-continuing, log the exception with stack, not just "error occurred". An except-pass block is a crime scene with the evidence removed.
- Match the failure to the audience: user-facing messages say what the user can do ("file too large, max 10MB") and never leak internals (paths, SQL, stack traces — see security-reflex); operator-facing logs get the internals precisely so operators don't have to reproduce.
- Make messages greppable: stable phrasing with the variable parts as values (
"payment declined: code=%s order=%s"), so the on-call can search logs and code for the same string. Don't dynamically assemble the constant part.
- Log at the decision points you'd want during the outage: the request that entered, the branch taken, the external call and its outcome. If a bug just cost you an hour because nothing logged the crucial value, add the log line that would have saved you — that's the cheapest reliability work there is.
- Right level: errors are actionable problems; warnings are tomorrow's errors; info is narrative. Logging expected conditions as errors trains everyone to ignore errors.
Test: with only this message and no source access, could someone tell what to look at first? If not, it's missing a part.
