Eve library

OSHUN V1 Partial Failure and Degraded Mode Rules

Guide

Revision 1

On this page

Status: Accepted v1.0
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-020
Related:

  • docs/releases/v1/scope/minimal-chrome-rules.md
  • docs/releases/v1/scope/scan-first-content-hierarchy-rules.md
  • docs/releases/v1/runbooks/studio-resilience-and-error-ux-runbook.md
  • docs/releases/v1/specs/todos.md

1. Purpose#

This document defines the canonical visual and interaction rules for partial failure and degraded mode across OSHUN customer and admin surfaces.

The core requirement is:

  • preserve orientation
  • preserve trust
  • preserve progress when possible
  • explain what still works
  • show the next safe action

A failure state should never make the product feel more broken than the actual underlying condition.

2. Definitions#

2.1 Partial Failure#

A partial failure means one capability, section, or dependency has failed while the broader surface can still function.

Examples:

  • one domain feed fails inside an otherwise working shell
  • search suggestions fail but typed search still works
  • one panel in an admin workspace cannot load while the rest of the cockpit is still available

2.2 Degraded Mode#

Degraded mode means the product intentionally limits capabilities to preserve safety, continuity, or responsiveness.

Examples:

  • cached fallback content replaces live content
  • write actions queue until connectivity returns
  • one provider path is disabled while another remains available
  • admin incident workflows remain active with reduced observability or control

2.3 Unavailable#

Unavailable means the user cannot use the intended surface right now and needs retry, fallback, or redirection.

2.4 Crash Boundary#

A crash boundary is the last-resort containment surface when rendering or runtime failure escapes normal error handling.

3. Core Rules#

3.1 Fail Locally Before Failing Globally#

If a single panel, domain, or task can fail without breaking the rest of the shell, keep the failure local.

Do not replace an entire shell with a full-page error if:

  • one section failed
  • one domain dependency failed
  • one action failed and can be retried

3.2 Preserve What Still Works#

Every degraded state should make the following explicit:

  • what failed
  • what still works
  • what the user can do next

If the message only says something is broken, it is incomplete.

3.3 Recovery Must Be Visible#

Every meaningful failure or degraded state needs at least one visible recovery path:

  • retry
  • continue with fallback
  • queue for later
  • switch surface
  • go back safely

3.4 Calm Beats Drama#

Most recoverable failures should feel calm, not catastrophic.

Use visual escalation only when:

  • data loss risk exists
  • a security boundary is involved
  • an operator must escalate immediately
  • the user cannot safely continue

4. Canonical State Ladder#

State When to use User promise Default dominant action
silent retry transient issue likely to self-recover quickly no disruption unless delay becomes meaningful none
inline partial failure one block or section failed the broader surface still works retry section / continue elsewhere
local degraded mode fallback is active inside a section or route reduced capability, preserved continuity continue with fallback / retry
screen-level degraded mode the intended route is usable only in limited mode preserve progress with visible limits continue in degraded mode / switch route
surface unavailable the route or domain is currently not usable try again or move to another safe path retry / switch surface
global offline or shell-wide degradation connectivity or platform dependency affects many flows shell still works where possible, writes may queue retry connectivity / sync later
crash boundary rendering/runtime failure escaped normal handling the shell or route can be reset safely retry / return to stable shell

5. Visual Posture Rules#

5.1 Tone Ladder#

Use tone based on recoverability, not on fear.

  • neutral/info: queued, syncing, low-risk fallback
  • warning: partial failure, limited capability, degraded mode
  • danger: blocking failure, destructive risk, unrecoverable error, explicit data integrity risk

Do not use danger styling for every retryable network issue.

5.2 Layout Posture#

Partial failure surfaces should preserve the surrounding layout whenever possible.

Preferred patterns:

  • inline state block in the failed section
  • lightweight panel replacement
  • persistent shell with local notice
  • slim global offline banner for shell-wide connectivity issues

Avoid jumping straight to:

  • full-screen empty voids
  • modal interruptions for recoverable states
  • complete shell replacement when the shell still works

5.3 Message Anatomy#

Customer-facing failure states should usually include:

  • clear title naming the impacted surface
  • one sentence explaining the impact
  • one sentence naming what still works or what fallback is active
  • one dominant action
  • one safe alternate path

Operator-facing failure states should include:

  • affected workflow or surface
  • current severity or degradation state
  • active capability limits
  • next recovery or escalation step
  • auditability or ownership context when relevant

6. Customer Rules#

6.1 Customer Partial Failures#

Customer partial failures should be:

  • specific
  • calm
  • actionable
  • continuity-preserving

Examples:

  • "Live activity is temporarily unavailable. Showing local fallback timeline."
  • domain route unavailable with a retry path and alternate domain links
  • offline mode showing cached content and queued-action posture

6.2 Customer Degraded Mode#

Degraded mode for customer surfaces must emphasize continuity:

  • cached content stays readable
  • queued actions are acknowledged
  • users know whether a write will sync later
  • alternate domains remain reachable when possible

6.3 Customer Crash Boundaries#

Crash boundaries should:

  • reassure the user their broader session is still safe
  • offer a retry
  • avoid technical overload by default
  • keep detail behind disclosure when needed

7. Admin And Operator Rules#

7.1 Admin Partial Failures#

Admin partial failures must be more explicit than customer ones.

They should name:

  • impacted workflow
  • affected capability
  • current severity
  • whether degraded mode is active

7.2 Admin Degraded Mode#

Operator degraded mode is not just a softer error state. It is a controlled operating posture.

It must make visible:

  • blocked capabilities
  • fallback path or manual override availability
  • recovery action type
  • escalation or ownership state when required

7.3 Admin Unavailable States#

If an operator route becomes unavailable:

  • keep the cockpit shell available
  • preserve navigation to adjacent workspaces
  • surface the next safe path, not just the failure

Admin should never strand the operator in a dead-end full-page error without a route back into working operations.

8. Action Rules#

8.1 One Dominant Recovery Action#

Every failure block gets one dominant next step:

  • Try again
  • Continue with fallback
  • Sync now
  • Open incident workspace
  • Return to shell

Do not present five equivalent recovery buttons.

8.2 Retry Must Mean Something#

Retry actions should be shown only when the underlying action is genuinely retryable.

If retry is not safe or not meaningful, the primary action should instead be:

  • queue for later
  • switch to fallback
  • escalate
  • go back

8.3 Alternate Paths Matter#

When one domain or route is unavailable, the state should offer at least one alternate working path when possible.

The current domain route fallbacks and shell-level alternative-domain links are valid canonical patterns.

9. Copy Rules#

9.1 Name The Broken Thing#

Say what failed:

  • domain
  • panel
  • sync
  • search
  • audio
  • queue
  • workflow

Avoid generic copy such as:

  • "Something went wrong" for every condition
  • "Unexpected error" when the failure is actually understood

9.2 State The Preservation Promise#

Where true, say explicitly:

  • your data is safe
  • your actions were queued
  • cached content remains available
  • other domains still work
  • the rest of the shell is still available

9.3 Keep Technical Detail Secondary#

Technical detail belongs in:

  • expandable detail sections
  • operator-only contexts
  • audit or diagnostics surfaces

Default customer states should not lead with stack traces or internal codes.

10. Explicit Anti-Patterns#

These are non-canonical for OSHUN V1:

  • full-screen error replacement for a single failed module
  • bright destructive styling for recoverable offline states
  • failure states that do not say what still works
  • retry buttons with no alternate path
  • degraded mode that hides capability limits
  • blank skeletons that never resolve into a visible fallback state
  • shell crash states that trap the user without recovery or safe navigation

11. Current Implementation Targets#

These rules should directly govern and refine the current failure-state surfaces already present in the repo:

  • apps/oshun/web/src/components/DomainDegradation.tsx
  • apps/oshun/web/src/components/OfflineBanner.tsx
  • apps/oshun/web/src/components/DomainErrorBoundary.tsx
  • apps/oshun/web/src/design-system/components/ErrorState.tsx
  • apps/oshun/web/src/components/DomainRouteExperience.tsx
  • apps/oshun/mobile/src/offline/GlobalOfflineBanner.tsx
  • apps/oshun/mobile/src/components/OshunErrorBoundary.tsx
  • apps/oshun/mobile/src/__tests__/nonfunctional/api-resilience.test.ts
  • apps/oshun/web/src/components/studio/StudioResilienceErrorUxWorkspace.tsx

12. Exit Standard#

A partial failure or degraded-mode surface is correct only when:

  • the failure scope is accurate
  • the rest of the product remains usable where possible
  • the user understands what still works
  • the next safe action is obvious
  • the visual treatment matches the actual severity

If the state feels vague, dead-end, or more alarming than the real condition, it is not acceptable for V1.