# OSHUN V1 Error, Outage, and Fallback Copy Guidance

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

- `docs/releases/v1/design/ux-principles.md`
- `docs/releases/v1/design/readability-standards.md`
- `docs/releases/v1/scope/partial-failure-and-degraded-mode-rules.md`
- `docs/releases/v1/scope/canonical-loading-skeleton-empty-offline-error-state-rules.md`
- `docs/releases/v1/runbooks/studio-resilience-and-error-ux-runbook.md`
- `apps/oshun/web/src/design-system/components/ErrorState.tsx`
- `apps/oshun/web/src/components/OfflineBanner.tsx`
- `apps/oshun/web/src/offline/GlobalOfflineBanner.tsx`
- `apps/oshun/web/src/components/DomainRouteExperience.tsx`
- `apps/oshun/web/src/components/DomainDegradation.tsx`
- `apps/oshun/mobile/src/components/OshunErrorBoundary.tsx`
- `apps/oshun/mobile/src/offline/GlobalOfflineBanner.tsx`
- `apps/oshun/mobile/src/i18n/strings.ts`
- `docs/releases/v1/specs/todos.md`

## 1. Purpose

This document defines the canonical copy rules for errors, outages, degraded
mode, and fallback behavior across OSHUN V1.

The copy standard exists so failure states feel:

- calm
- precise
- trustworthy
- action-oriented
- proportional to impact

Failure copy must never make the product feel more broken than it is, and it
must never hide risk that the user actually needs to understand.

## 2. Current Repo Signals, External Scan, And Gap

The current repo already contains useful baseline language:

- web and mobile offline banners use explicit titles such as
  `Offline mode active`, `Syncing queued actions`, and `Queued actions pending`
- the shell offline banner already says
  `You are offline. Some features may be unavailable.`
- web and mobile crash surfaces use calm recovery wording such as
  `You can safely retry and continue your session.`
- domain route and degradation surfaces already distinguish
  `temporarily unavailable`, offline fallback, queueing, and alternate routes
- partial-failure and state-ladder docs already separate `offline`,
  `degraded mode`, `local error`, `screen unavailable`, and `crash boundary`

External implementation research reinforces several patterns:

- GOV.UK guidance sharply separates user-fixable validation errors from
  service-side failures the user cannot fix.
- GOV.UK error guidance favors plain language, specific recovery instructions,
  and preserving the user's entered data rather than clearing it.
- Atlassian error-message guidance emphasizes short titles, one to two sentences
  of body copy, next-step clarity, and avoiding filler such as repeated
  apologies.
- Atlassian Statuspage incident guidance stresses communicating early, stating
  known impact, updating on a predictable cadence, and owning the problem even
  when an upstream dependency caused it.
- Atlassian Statuspage templates consistently name the condition in plain
  language: `Service disruption`, `Trouble logging in`, `Elevated API Errors`,
  `Connectivity issues`.

Inference from those sources plus the repo state:

- OSHUN has most of the structural resilience grammar already.
- OSHUN still needs one copy contract explaining how failure language should
  sound, what promises it may or may not make, and how to write messages for
  each failure tier.

## 3. Canonical Thesis

OSHUN failure copy should do five things in order:

1. name the user-visible condition
2. explain the practical impact
3. say what still works, if anything
4. present the best next action
5. keep technical detail behind a deeper layer unless the user truly needs it

The default posture is:

- direct, not dramatic
- honest, not overconfident
- useful, not ornamental

## 4. Core Rules

### 4.1 Name The Condition The User Can Observe

Prefer:

- `Offline mode active`
- `Tara is temporarily unavailable`
- `Queued actions pending`
- `Syncing queued actions`
- `This section could not load`

Avoid:

- `Unexpected exception`
- `Service layer failure`
- `Provider transport error`
- `An error occurred`

### 4.2 Say What The User Can Still Do

If fallback, cache, or queueing is active, say so explicitly.

Good:

- `Cached content is still available.`
- `Your action is queued and will sync when connection returns.`
- `You can continue in another domain while this one recovers.`

Bad:

- `Limited functionality`
- `Some systems are impacted`

The second set is too vague to guide recovery.

### 4.3 Never Over-Promise Safety Or Recovery

Do not promise:

- data is safe
- nothing is lost
- retry will work
- sync will succeed soon

unless the system truly guarantees that claim.

Use controlled wording instead:

- `Your action is queued locally and will sync when connection returns.`
- `You can try again now or continue with cached content.`
- `We have reported this issue automatically.`

Avoid:

- `Your data is safe and will be available when the service recovers.`
- `Nothing was lost.`
- `This will be fixed shortly.`

### 4.4 Differentiate User Errors From Service Problems

User-fixable issues should tell the user what to correct.

Service-side problems should tell the user what changed in the service and what
path remains available.

Do not use form-field error language for outages, permissions, or missing
service capacity.

Examples:

- user-fixable: `Enter your note title`
- service-side:
  `Notes are temporarily unavailable. Try again or return to your library.`

### 4.5 Keep Titles Short And Bodies Shorter

Default target:

- title: 3 to 6 words
- body: 1 to 2 sentences

If the state needs more explanation, move detail into:

- expandable technical details
- a linked incident or status surface
- a dedicated admin diagnostics panel

### 4.6 Use One Dominant Recovery Action

The main action should tell the truth about what it does.

Preferred labels:

- `Try again`
- `Sync now`
- `Continue with fallback`
- `Return to library`
- `Open incident workspace`

Avoid weak or generic buttons such as:

- `OK`
- `Dismiss`
- `Continue`

unless that really is the only honest action.

### 4.7 Avoid Automatic Apology Language

Do not default to:

- `Sorry`
- `Oops`
- `Please try again`

for routine retryable failures.

Empathy is appropriate for meaningful disruption, but OSHUN should still sound
steady and operational, not flustered.

### 4.8 Technical Details Belong Behind Disclosure

Codes, traces, provider names, and stack details should not lead the primary
message unless the audience is explicitly operator-facing.

Customer primary copy should describe impact.

Operator copy may add:

- incident ID
- affected dependency
- severity
- fallback mode
- owner or escalation path

## 5. Canonical Vocabulary

### 5.1 Preferred Terms

- `temporarily unavailable`
- `offline`
- `queued`
- `syncing`
- `degraded mode`
- `cached content`
- `fallback`
- `try again`
- `return`
- `open status`
- `open incident workspace`

### 5.2 Terms To Avoid

- `catastrophic`
- `fatal`
- `meltdown`
- `oops`
- `broken`
- `crashed` unless the surface literally hit a crash boundary
- `forbidden`
- `invalid` as the only explanation
- `unknown error`

## 6. Scenario Rules

### 6.1 Validation Errors

Validation errors should:

- refer directly to the field or question label
- say what to change
- preserve the entered value
- avoid examples if the example is already visible in hint text

Good:

- `Enter your note title`
- `Search term must be 80 characters or less`

Bad:

- `This field is invalid`
- `Answer the question`

### 6.2 Retryable Action Failures

Retryable failures should say the action failed, not the whole app.

Good:

- `This section could not load. Try again.`
- `We could not refresh this queue. Try again or continue with the current view.`

Bad:

- `Something went wrong`

unless the error boundary genuinely cannot localize the failure any further.

### 6.3 Offline With No Queued Writes

Copy should focus on reduced capability, not panic.

Good:

- `Offline mode active`
- `Some features may be unavailable until you reconnect.`

### 6.4 Offline With Queued Writes

Copy should acknowledge the queued state explicitly.

Good:

- `3 actions queued until connection returns.`
- `Queued actions pending`
- `Sync now`

Rules:

- state the count when available
- make queueing sound durable and intentional, not like a silent maybe
- do not imply the server already received the write

### 6.5 Sync In Progress

Good:

- `Syncing queued actions`
- `Sending 4 queued actions...`

Do not say:

- `Recovered`
- `Complete`

until the sync actually finishes.

### 6.6 Degraded Mode With Fallback Active

Degraded-mode copy must say both the limit and the preserved path.

Good:

- `Live activity is temporarily unavailable. Showing cached activity instead.`
- `Search suggestions are unavailable. You can still run a full search.`

Bad:

- `Reduced functionality is active.`

### 6.7 Route Or Domain Unavailable

When the intended route cannot function:

- name the affected route or domain
- say it is temporary when that is the expectation
- offer one primary retry path and one alternate route

Good:

- `Nisaba is temporarily unavailable`
- `Retry launch or switch to another domain.`

### 6.8 Crash Boundaries

Crash boundaries should be steady and narrow in promise.

Good:

- `Something went wrong`
- `OSHUN hit an unexpected issue. You can safely retry and continue your session.`

Rules:

- reassure only what the system actually knows
- say whether reporting happened automatically only when telemetry confirms it
- offer retry and one safe exit path

### 6.9 Incident, Outage, And Status Updates

Incident updates should follow the strongest current status-page patterns:

- acknowledge the issue early
- summarize known impact
- state mitigation or fallback if known
- state when the next update will come if there is a public cadence

Good:

- `Some users may be experiencing trouble signing in. We are investigating and will share another update in 30 minutes.`
- `We are seeing elevated API errors. Cached reading remains available while we investigate.`

Bad:

- `We are aware of reports`
- `The vendor is having issues`

without stating the impact on OSHUN users.

## 7. Canonical Templates

These templates are the preferred starting point for new OSHUN surfaces.

### 7.1 Inline Or Section Retry

- Title: `This section could not load`
- Body:
  `Try again. If the issue continues, continue with the rest of the page and return later.`
- Action: `Try again`

### 7.2 Offline Banner

- Title: `Offline mode active`
- Body: `Some features may be unavailable until you reconnect.`
- Action: `Retry` or `Sync now` when meaningful

### 7.3 Offline Queue

- Title: `Queued actions pending`
- Body: `{count} action(s) queued until connection returns.`
- Action: `Sync now`

### 7.4 Degraded Fallback

- Title: `{surface} is limited right now`
- Body:
  `Live data is temporarily unavailable. Showing cached or fallback content instead.`
- Action: `Try again` or `Continue with fallback`

### 7.5 Route Unavailable

- Title: `{domain} temporarily unavailable`
- Body: `Retry this route or switch to another domain.`
- Action: `Retry launch`

### 7.6 Crash Boundary

- Title: `Something went wrong`
- Body: `You can retry now or return to a stable OSHUN surface.`
- Actions: `Try again`, `Home`

### 7.7 Incident Status Update

- Title: `{surface} service disruption`
- Body:
  `We are investigating an issue affecting {impact}. {fallback_or_next_update}`

## 8. Do And Do Not Examples

### 8.1 Generic Error

- do: `This section could not load. Try again.`
- do not: `An unexpected application error has occurred.`

### 8.2 Offline

- do: `You are offline. Some features may be unavailable.`
- do not: `Network transport failure detected.`

### 8.3 Queueing

- do: `2 actions queued until connection returns.`
- do not: `Your changes should probably sync later.`

### 8.4 Degraded Mode

- do:
  `Live search suggestions are unavailable. You can still run a full search.`
- do not: `Reduced functionality is currently in effect.`

### 8.5 Domain Outage

- do:
  `Veritas is temporarily unavailable. Retry launch or switch to another domain.`
- do not: `Veritas backend dependency failed.`

### 8.6 Crash Boundary

- do:
  `OSHUN hit an unexpected issue. You can safely retry and continue your session.`
- do not: `Oops. We broke something.`

## 9. Definition Of Done

Error, outage, and fallback copy is done for a surface only when:

- the message names the observable condition
- the copy distinguishes user-fixable issues from service-side failures
- the message says what still works when continuity exists
- the primary action is explicit and meaningful
- the copy avoids unsupported safety or recovery promises
- technical detail stays secondary unless the audience is operator-facing
- incident and outage updates communicate impact, cadence, and ownership clearly
