Honest failure surfacing

Three field incidents where the surface lied about what failed, plus a storage failure that stayed invisible for hours behind a swallowing loop and a cosmetic progress bar. Layer: norm + playbook — the one-line norm in the global CLAUDE.md is the everyday trigger; this file is the depth.

The rule

Every distinct failure mode gets its own user-facing message; never collapse them into one reassuring string. A surface that cannot say what failed sends the user (and the developer) to fix the wrong thing.

How to apply

• Classify before wording. A catch block once painted every transcription failure as "No connection" while the real cause was a malformed-JWT 401 — costing hours of a field inspection. Distinguish at minimum: auth, offline, server, and input failures.
• A disabled control cannot explain itself. A disabled button swallows the tap, and the handler holding the explanation never runs. If a control can legitimately fail a precondition, let it be pressed and have it say why.
• Per-item failures in a loop surface to the user, not just to a log. A sync loop that swallowed per-photo upload errors showed a fake "Uploading…" pulse forever; nothing was uploading. Progress UI reflects real progress or it is a lie.
• A permanently-failed item is surfaced as given up, not silently retried forever — and never allowed to wedge the rest of the queue.
• Error level is for terminal states. Self-healing retries logged at error drowned the one terminal give-up that mattered. Retries log at warning; the give-up logs at error.

What this skill does not do

It does not decide what happens to the data on a failing path — no-silent-data-drop owns content preservation. It does not define skip semantics in tests — prove-it-can-fail owns check integrity.

Why

A wrong error message is worse than none: it actively redirects diagnosis. Every incident in the evidence cost hours specifically because the surface asserted a cause it had not established. Evidence: ASH LESSONS_LEARNED 2026-05-28, 2026-06-18, 2026-07-14 (offline), and the CLAUDE.md storage-RLS upsert lesson; ICC L-007 (shared evidence with guard-the-spend-paths).

Additions from the misses-log sweep (2026-10-22)

• Bound every await on the path, not the one holding the fetch. A network wait is bounded end to end: reading or refreshing the credential, each third-party client call, the request and the body (keep the timer running until the body is read). A test hangs each stage and asserts the call ends. (ICC L-103.)
• A long silent call looks like a hang. Keep each tool call or step to a couple of minutes, write output to disk in stages, and say what is still running between them; a session that shows nothing for fourteen minutes cannot be told from a stuck one. (Factorio Mods, 2026-10-18.)