0003 - Standardize Runtime Error Handling and Recovery

Status: Accepted Date: 2026-03-29 Author: Codex

Context

Across PRDs 01 through 10, the intended happy path is usually clear, but recoverable runtime failures are often left implicit. That creates the same implementation risk in multiple places:

• Wizards do not define what happens when the final save fails
• Feed and list specs do not distinguish empty from error
• Some actions imply optimistic UI updates without rollback rules
• Push notifications are treated as primary user feedback even when delivery can fail
• External dependencies such as maps, typeahead vocabularies, browsers, forms, and widgets do not define degraded behavior

Without a shared standard, frontend and backend teams will make inconsistent choices about retries, rollback, draft preservation, loading states, and fallback UX.

Decision

Feel Pro Club will treat runtime error handling and recovery as a first-class product requirement, not an implementation detail.

1. Every PRD must include an Error States section covering the primary recoverable failures for that feature.
2. User-facing loads must distinguish at least these states when relevant: loading, empty, error, and timeout/stale.
3. Failed submissions for forms and wizards must preserve the user's current input or draft, keep the user in context, and provide a retry path.
4. Optimistic UI updates are allowed only when rollback behavior is explicitly defined. If persistence fails, the UI must restore the last confirmed server state and explain what happened.
5. External-service dependencies must define a degraded mode. If the dependency is temporarily unavailable, the product must either provide a retry path, a cached/manual fallback, or a blocked-but-explained state.
6. Multi-step or cascading operations must be atomic from the user's point of view whenever possible. If true atomicity is not possible, the UX must expose in-progress state, authoritative final state, and any required compensation behavior.
7. Critical outcomes must remain visible in-product even when notification delivery fails. Push notifications are an enhancement, not the sole confirmation mechanism.

Consequences

Positive

• PRDs become testable for failure handling instead of only for happy paths
• Frontend and backend implementations get a shared contract for retries, rollback, and degraded states
• Users are less likely to lose work or misread a failed action as a successful one
• Cross-feature behavior becomes more consistent, especially in onboarding and team-management flows

Negative

• PRDs become longer and require more upfront thinking
• Some features will need additional product and design work for degraded modes
• Implementation may take longer because draft persistence, rollback, and compensation must be built deliberately

Mitigations

• Keep Error States sections focused on the highest-impact recoverable failures, not every theoretical outage
• Reuse the same product patterns across features: retry, preserved draft, unavailable-resource screen, optimistic rollback, and in-progress destructive states
• Reference this ADR during implementation and QA so teams do not redefine the same behavior repeatedly