Failure output

What a user, test, or operator sees when work fails.

25 items in this guidance cluster.

Tagged guidance

Observability and failureObservability and failure guidance covers Rust and service boundaries where failures need to be understandable after the fact. It favors structured errors, owned logging boundaries, distinct failure states, safe diagnostics, and enough context for the owner to act.

Define hook failure policySpecify whether each hook class blocks, retries, logs and continues, rolls back, or leaves partial state. This gives extension points predictable failure behavior without forcing one global answer onto every hook.Distinguish input classesKeep unknown, unsupported, denied, and preserved inputs in separate result or error paths. The distinction protects compatibility, authorization messaging, and recovery behavior while allowing small internal parsers to stay simpler.Expose partial stream outputSurface streaming tokens, chunks, or events as provisional output until completion promotes a final result. Callers get progress and diagnostics without corrupting authoritative state with partial provider data.Report provider diagnosticsReturn freshness, permission, budget, load, cache, partial-result, and degradation signals with provider-backed data. These diagnostics help callers decide trust, retry, display, and support behavior without exposing unactionable internals.

Distinguish failure statesPreserve status distinctions that change recovery, messaging, metrics, or debugging. Collapsing timeouts, denials, aborts, partial work, and failures makes callers guess.Keep diagnostics retention safeMatch diagnostic detail to its audience and retention period. Redact or summarize sensitive values while preserving enough operation context to debug.Keep recovery advice safe and honestGive recovery advice only when the program knows enough to make it safe. Report observed facts, label uncertainty, and avoid destructive, security-weakening, or policy-bypassing next steps unless the current state proves they are appropriate.Match failure output to surfaceChoose a failure-output surface that lets the affected user notice, understand, and act on the failure. Inline errors, alerts, toasts, banners, persistent status, CLI stderr, API responses, and support artifacts have different affordances and failure modes.Preserve operation context in errorsCarry the operation, resource, provider, input class, and policy context that explain a failure. Stable identifiers and sanitized summaries shorten debugging without exposing payloads.Surface durable failuresGive persistent failures a stable status, error surface, or retry path instead of only an ephemeral UI log. Users and maintainers need something actionable after the moment passes.

Implement debug for public typesProvide Debug for public types unless it would expose secrets or mislead callers. The trait is baseline support for tests, assertions, logs, and downstream diagnostics.Keep lints actionableEnforce lints that improve correctness, API quality, docs, portability, or maintenance in ways reviewers want automated. Scope suppressions tightly so exceptions stay visible.Name tests by behaviorName tests after the behavior, boundary, or regression they protect so failure output is useful before a reader opens the body. Keep names concise and let module context carry repeated setup details.Preserve error contextWrap and model errors so callers can see the operation, relevant input, source cause, and recovery signal. Avoid flattening failures into broad strings or generic variants that remove actionable context.Use debug assert for internal invariantsUse debug assertions for internal invariants that should hold if nearby code is correct. Do not use them for caller validation or safety requirements that must be enforced in release builds.Write actionable error displayWrite Display messages that tell humans what failed and what useful next action or context exists. Keep structured state in error fields, sources, diagnostics, or Debug instead of dumping internals into the user-facing string.

Avoid opaque boolean assertionsPrefer comparisons or richer assertions when a predicate hides state needed to diagnose the failure. The first failure should show the useful actual value.Optimize failure outputDesign tests so failures include expected values, actual values, inputs, and contract context where that helps repair. Useful output shortens CI and agent debugging loops.Split unrelated assertionsSplit assertions that diagnose different behaviors when one failure would hide another. Keep checks together only when they express one contract more clearly as a group.

Make failures observableErrors without diagnostic context force future readers and operators to rediscover what failed. Preserve typed errors while adding operation context, correlation, metrics, or logs at the boundary that owns the meaning.Preserve error contextErrors often lose the facts a caller needs when they cross module, process, support, or user boundaries. Preserve stable kinds and actionable context so callers can retry, report, recover, or correlate the failure without parsing generic text.Shape tool output for agentsHuman-oriented tool output can bury the failure signal an agent needs to act. Prefer quiet summaries, structured output, and saved full logs so agents see the actionable slice first without losing debugging context.Write actionable error messagesAccurate error messages can still leave users, operators, callers, or support unable to act. Design failure output so the audience can find the attempted operation, affected item, known cause, impact, next step, and diagnostic handle when those facts matter.

Tests should explain failuresA failing test should point at the broken contract, not merely report that a predicate was false. Choose assertion shapes that expose the relevant value, variant, order, or case name.