Say what happened, why, and what to do

What it is

A diagnostic and recoverable error message answers what outcome occurred, why when that can be stated safely, and what next step can restore the user's goal. It also reports critical state: whether a draft was saved, a charge occurred, or an operation partially completed. These are not mandatory sentence slots. When the cause is genuinely unknown, state uncertainty and offer an action that remains valid instead of inventing a “why.”

Why it happens

An error breaks the user's prediction of system state and task path. What corrects the current state, why rules out ineffective attempts, and next step reconnects the path. “Something went wrong” leaves users unsure whether to repeat work; an unsupported network attribution sends repair effort to the wrong place; perpetual “Retry” loops when the fault is not retryable. Recovery must match the error class, actual data state, user authorization, and service availability.

Studying it

Inject representative faults across transient/persistent, user-fixable/system-owned, complete/partial success, and data-risk conditions. Ask users to restate state and recover; measure first correct recovery, repeated failure, time back to goal, abandonment, and help seeking while checking actual logs. Study unknown states separately to ensure the message neither fabricates a cause nor strands users without ways to preserve work, try later, or seek support with a reference.

Where it stops holding

Not every message needs three explicit sentences. A self-healed fault with no user impact may stay quiet, and an obvious low-risk transient failure can be concise. Explain cause only to the level useful for action and safe to disclose, never internal architecture or security rules. A next step must be available, reachable, and authorized. When recovery is unavailable, state the limit and support route honestly rather than promising success.

Applying it

• Define outcome, safely disclosable cause, data or transaction state, recovery action, action availability, and escalation path for each error; model unknown explicitly.
• Generate a complete result–cause/unknown–next-step message and place the executable action beside it. For partial success, distinguish completed and incomplete scope.
• Give retry a prerequisite, progress state, and exit after repeated failure. Route quota, authorization, and permanent states directly to the viable resolution.
• Regress copy against actual state in a fault matrix. Block release for false attribution, unavailable actions, or omitted data and charge status.

Related

• Same group: T2.04.2 Do not blame the user in error messages · T2.04.3 Do not expose internal technical detail · T2.04.4 Do not joke away real losses · T2.04.5 Same-class errors need consistent wording
• Adjacent: T2.05.1 Distinguish no-data, no-match, and error states · T2.05.2 Empty states need an explicit next action
• Search terms: error diagnosis · recovery path · unknown state