# OSHUN V1 Partial Failure and Degraded Mode Rules

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.
