Failure Output

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

25 items in this guidance cluster.

Tagged guidance

GuideObservabilityErrorsSecurity PrivacyObservability And Failureobservability-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.

RuleBoundary CorrectnessAsyncErrorsDefine Hook Failure PolicyBOUNDARY-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.RuleBoundary CorrectnessValidation PolicyErrorsDistinguish Input ClassesBOUNDARY-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.RuleBoundary CorrectnessAsyncState TransitionsExpose Partial Stream OutputBOUNDARY-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.RuleBoundary CorrectnessObservabilityErrorsReport Provider DiagnosticsBOUNDARY-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.

RuleObservabilityErrorsState TransitionsDistinguish Failure StatesOBSERVABILITY-DISTINGUISH-FAILURE-STATESPreserve status distinctions that change recovery, messaging, metrics, or debugging. Collapsing timeouts, denials, aborts, partial work, and failures makes callers guess.RuleObservabilitySecurity PrivacyKeep Diagnostics Retention SafeOBSERVABILITY-KEEP-DIAGNOSTICS-RETENTION-SAFEMatch diagnostic detail to its audience and retention period. Redact or summarize sensitive values while preserving enough operation context to debug.RuleObservabilityErrorsSecurity PrivacyKeep Recovery Advice Safe and HonestOBSERVABILITY-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.RuleObservabilityErrorsMatch Failure Output To SurfaceOBSERVABILITY-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.RuleObservabilityErrorsBoundary CorrectnessPreserve Operation Context in ErrorsOBSERVABILITY-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.RuleObservabilityErrorsState TransitionsSurface Durable FailuresOBSERVABILITY-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.

RuleRustPublic APISecurity PrivacyImplement Debug for Public TypesRUST-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.RuleRustToolingAutomationKeep Lints ActionableRUST-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.RuleRustTestingReviewabilityName Tests By BehaviorRUST-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.RuleRustErrorsObservabilityPreserve Error ContextRUST-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.RuleRustValidation PolicyUse Debug Assert For Internal InvariantsRUST-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.RuleRustErrorsObservabilityWrite Actionable Error DisplayRUST-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.

RuleTestingReviewabilityAvoid Opaque Boolean AssertionsTEST-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.RuleTestingErrorsReviewabilityOptimize Failure OutputTEST-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.RuleTestingReviewabilitySplit Unrelated AssertionsTEST-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.

PatternObservabilityErrorsMake Failures Observablemake-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.PatternErrorsObservabilityPreserve Error Contextpreserve-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.PatternToolingAgent ContextShape Tool Output For Agentsshape-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.PatternErrorsPublic APIWrite Actionable Error Messageswrite-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.

PrincipleTestingVerificationTests Should Explain Failurestests-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.