Implement optimistic UI mutations with rollback safety

A portable discipline for the write path of any React/React Native app using a query/cache layer, building on frontend-data-contracts (writes go through the typed client) and frontend-architecture (mutations live in modules/{feature}/hooks/). Five core ideas: the optimistic lifecycle is fixed at five beats - cancel in-flight queries, snapshot every affected cache, patch instantly, roll back verbatim on error, invalidate on settle; rollback restores the exact prior snapshot from mutation context, never a re-derived guess; an idempotency key is generated once at form-init or first intent (not inside mutationFn, and not regenerated per retry) so a network retry replays the original server response instead of double-performing the action; caches move in lock-step - a status change patches the detail cache and every list page containing the entity together, so surfaces never disagree; and server state never leaves the query cache into a client store. A decision table sets when to be optimistic: high-confidence low-conflict writes (toggle status, like, mark-paid, reorder) go fully optimistic; creates returning server-generated ids/totals use a pending state seeded from the server response instead; destructive or hard-to-reverse writes (cascading delete, sending money) confirm first, never silent-optimistic; and writes with invisible results (background jobs) use pending-plus-toast with no optimistic patch. The reference TanStack Query shape shows onMutate canceling queries then snapshotting and patching both the detail cache and every list page, onError restoring both snapshots verbatim before surfacing the typed ApiError, and onSettled invalidating both regardless of success or failure so server-computed fields (timestamps, totals) become authoritative again. Retry policy is network-only and bounded (error.isNetworkError && count < 2), never retrying on 4xx, and 409 conflicts surface rather than retry so the user re-decides on fresh data. Library adapters cover TanStack Query's onMutate/onError/onSettled trio, RTK Query's updateQueryData patchResult with an undo() in catch plus invalidatesTags, and SWR's mutate() with rollbackOnError and populateCache - the five-beat lifecycle stays constant across all three, and React Native works unchanged since the cache is the source of truth there too.

Use it when implementing or reviewing mutations in a React/React Native app with a query/cache layer - deciding whether a write should be optimistic, implementing the cancel/snapshot/patch/rollback/invalidate lifecycle, making a write safely retryable, or keeping detail and list caches coherent after a change.

Given a mutation and the set of caches an entity appears in, it produces a hook implementing the five-beat lifecycle: an onMutate patch with snapshots, an onError rollback, and an onSettled invalidation, wired to the typed apiClient and ApiError from frontend-data-contracts.

onMutate: async ({ id }) => { await queryClient.cancelQueries({ queryKey: invoiceKeys.all }); /* snapshot + patch */ }

Works with TanStack Query, RTK Query, or SWR as the underlying cache library, and pairs with the typed apiClient and ApiError from the frontend-data-contracts skill for the actual network call.

Frontend teams implementing writes that need to feel instant, fail safely with exact rollback, and keep every cache (detail plus all list pages) coherent - avoiding the most common write-path bugs: race-clobbered optimistic state from a missing cancelQueries, partial cache patches that leave surfaces disagreeing, and idempotency keys generated inside mutationFn that no longer protect retries.