| name | design-loud-failures |
| description | Design systems so a failure can never present as success. Use when building or reviewing pipelines, extractors, reconciliations, checkers, or any computation whose output humans act on; when missing inputs, unreadable files, or crashes could pass silently; when a tool "found" an explanation that feels too convenient; or on "make this fail loudly", "could this lie to us", "harden the failure paths". Produces named invariants, explicit skip and no-answer states, honest cause classes, and adversarial regression fixtures. |
Design Loud Failures
The dangerous state is not "the system failed." It is "the system failed and said
everything was fine." A wrong answer delivered with confidence costs more than no answer,
because humans act on it and stop checking. Every step below removes one way a system can
lie.
1. Name your invariants; do not search for coincidences
Verify the identities the domain guarantees ("these two totals must match", "parts must
sum to the whole") instead of searching combinations of values for something that agrees
within a tolerance. An unconstrained search over enough combinations will eventually
manufacture a plausible explanation for a real defect, and the defect ships wearing an
excuse. If you cannot name the invariant, you do not have a check; you have a slot machine.
2. Make "not provided" a first-class state
When an optional input is absent, the result is a named skip state: "not provided". Never
a fake pass (the check did not run), and never a leaked failure marker such as a sentinel,
placeholder, or error string flowing onward as data. Skips are reported alongside passes
and failures so a reader can see what was not checked.
3. Report the real cause class for unreadable inputs
When an input cannot be processed, distinguish the causes: extraction returned nothing,
the layout or format changed, the process crashed. Reporting the wrong cause ("file was
empty" when the parser crashed) sends humans to fix the wrong thing, and a tool that
misdiagnoses trains its users to ignore it. The diagnosis is part of the output contract.
4. Wrap every computation boundary
