Offline First Sync Architect

---
name: offline-first-sync-architect
description: 'Design the client offline data layer for a multi-tenant SaaS: durable write queue, optimistic projection with rejection handling that preserves conflicted unsynced edits, explicit conflict detection and resolution, local persistence, background sync, and integrity-checked reconciliation. Produces the sync-engine design, conflict policy, local-store and queue schema, and reconciliation contract. Use for offline/flaky-network behavior, reconnect conflicts, or lost/duplicated optimistic writes. Do NOT design offline UX states (edge-state-ux-designer), server caching (caching-strategy-designer), or online server-to-client push (realtime-subscription-architect). Refuse silent loss of conflict drafts.'
---

# Offline-First Sync Architect

**Reading key:** CRDT means conflict-free replicated data type, a data
structure whose copies merge automatically; LWW means last-write-wins; SSE
means server-sent events; authz means authorization; TTL means time to live,
the expiry limit for a cached value; ack means acknowledgement.

## Purpose

Offline-first is easy to demo and hard to get right: the demo shows an edit
made on a plane appearing after landing; the incident is two people editing
the same record offline and one silently losing their work, or a queued write
replaying twice and creating a duplicate, or an optimistic update that the
server rejected still sitting on screen as if it succeeded. This skill designs
the client offline data layer so those failure modes are handled by design:
the write-while-offline queue, optimistic apply with rollback on reject,
explicit conflict detection and a resolution policy chosen with eyes open,
local persistence, background sync, and reconciliation that preserves
integrity. The deliverable is the sync-engine design, the conflict-resolution
policy, the local-store and queue schema, and the reconciliation contract.
The single non-negotiable: a conflict that silently discards a user's data is
a bug, not a strategy — this skill refuses it.

## Use When

- Use when: the app must work offline or on flaky/intermittent networks —
  field apps, mobile, spotty-connectivity workflows — and needs a real sync
  layer, not just a spinner.
- Use when: queued offline edits conflict on reconnect and you need a
  detection + resolution policy (last-write-wins, field merge, CRDT, or
  manual).
- Use when: optimistic updates are getting lost, duplicated, or stranded on
  screen after a server reject, and the apply/rollback path needs designing.
- Use when: designing the local store (IndexedDB / SQLite / equivalent), the
  outbound write queue, and background sync semantics.
- Do NOT use when: the task is the UX of offline/loading/optimistic/error
  STATES — how "saved locally, will sync" or a rollback is presented to the
  user — that is `edge-state-ux-designer`; this skill is the sync ENGINE
  behind those states, and the two compose.
- Do NOT use when: the task is the SERVER-side or distributed cache (what to
  cache server-side, TTLs, invalidation) — that is `caching-strategy-designer`;
  a client offline store is not a server cache.
- Do NOT use when: the task is live server→client push while ONLINE
  (WebSocket/SSE channels, presence, subscribe-time authz) — that is
  `realtime-subscription-architect`; realtime is the online-delivery
  counterpart and can be the transport this engine syncs over, but it is a
  distinct concern (both skills' evals test this boundary from their own side).

## Inputs to Inspect

1. The offline requirement: which operations must work offline (read only?
   create? edit? delete?), for how long a device may be offline, and whether
   full offline or just resilience to blips.
2. The data shape: what is edited offline, its size (can it fit on-device),
   ownership (single-user records vs shared/collaborative), and how often two
   actors edit the same thing.
3. Concurrency reality: whether concurrent edits to the same record are
   common (drives conflict strategy) or rare (drives how much conflict
   machinery is justified).
4. The server write path (`command-gateway-architect` if present): whether
   writes are idempotent, carry a version, and can accept a client-generated
   id / idempotency key — the sync engine depends on this.
5. The tenant/auth model: how offline data is scoped and encrypted at rest on
   the device, and what happens to queued writes if the session/authority
   changes before they sync.
6. Existing behavior/pain: current optimistic-update handling, any incident
   history of lost edits or duplicate creates, and what "sync" does today.

## Workflow

For any user-facing build choice, define terms and each viable path's purpose;
compare case-specific pros/cons and money, setup, and maintenance costs (mark
unknowns). Recommend one and why, then ask one atomic decision question. If a
deciding fact is missing, ask only for that fact this turn. A choice does not
authorize execution.

1. **Scope the offline surface honestly.** Not everything needs to work
   offline. Classify operations: read-offline (cache + serve), create-offline
   (queue + optimistic), edit-offline (queue + optimistic + conflict risk),
   delete-offline (queue + tombstone). The more write surface offline, the
   more conflict machinery — justify each. Full offline for shared,
   frequently-co-edited data is the hardest case; say so.
2. **Design the local store and write queue.** The on-device store
   (IndexedDB/SQLite) holding the working data set and an ordered, durable
   outbound queue of pending writes. Each queued write carries: a
   client-generated id (idempotency key), the intended change, a base version
   (what the client last saw), and a timestamp. The queue survives app
   restart and is scoped/encrypted per the tenant/auth model.
3. **Design optimistic apply + rollback.** An offline write applies to the
   local projection immediately (optimistic) and enqueues. On sync, if the
   server ACCEPTS, confirm it. On validation or authorization rejection,
   retract the optimistic projection and explain the rejection. On conflict,
   retract the unconfirmed projection but retain the local edit as a conflict
   draft/queue entry for merge or manual resolution; never silently discard
   it. Tell the UX layer (`edge-state-ux-designer`) which state applies. An optimistic
   update that is never confirmed or rolled back — left on screen as if saved
   — is the core bug to avoid.
4. **Design conflict detection.** On sync, compare the write's base version
   against the server's current version. Same → clean apply. Diverged →
   conflict. Detection requires versioning (version number / vector clock /
   updated-at), so specify it. "No conflict detection" means silent
   last-writer-clobbers, which is the failure this skill refuses.
5. **Choose a conflict-resolution policy with eyes open.** Per data type:
   - **Last-write-wins** — simple, but DISCARDS the loser's edit; acceptable
     ONLY for low-stakes, single-owner, or naturally-idempotent data, and
     the discard must be acknowledged, never silent.
   - **Field-level merge** — non-overlapping field edits both survive;
     overlapping fields still need a tiebreak.
   - **CRDT** — automatic convergence for collaborative data, at real
     complexity/size cost; justify it, don't default to it.
   - **Manual resolution** — surface both versions to the user (UX via
     `edge-state-ux-designer`) when data is high-stakes and merge is unsafe.
   State the choice, the data it applies to, and what it costs the loser.
6. **Design background sync.** When connectivity returns: drain the queue in
   order, apply idempotently (the server dedups on the client-generated id so
   a retried sync never duplicates), handle partial-sync failure (some writes
   accepted, some rejected) transactionally per-write, and back off on
   repeated failure. Reconnection uses `realtime-subscription-architect`'s
   channel where present, but the queue drain is this engine's job.
7. **Design reconciliation + integrity.** After a sync, the local store
   converges to the server truth: pull server changes since the last sync
   cursor, merge with local per the conflict policy, and verify integrity
   (no duplicated creates, no resurrected deletes, tombstones honored). State
   the sync cursor mechanism and how a long-offline device catches up (full
   refresh vs incremental).
8. **Deliver** the sync-engine design, conflict policy, local-store + queue
   schema, and reconciliation contract in the Output Format, UX and transport
   handoffs named.

## Output Format

When asking for a build choice, show the explained options and justified
recommendation before the one question.

```
OFFLINE-FIRST SYNC DESIGN — <system/domain>
Offline surface: <per operation: read/create/edit/delete — offline? — conflict risk>
Local store + queue: <store tech; working set; durable ordered queue; per write:
  client-id (idempotency), change, base version, timestamp; scoped/encrypted>
Optimistic apply/rollback: <apply local projection; on accept confirm; on reject
  retract projection + notify UX; on conflict preserve unsynced draft for
  resolution; never leave unconfirmed-as-saved>
Conflict detection: <versioning mechanism (version/vector-clock/updated-at);
  base-version compare; diverged = conflict>
Conflict resolution (per data type): <LWW (with acknowledged discard) | field-merge
  | CRDT (justified) | manual (surface both)>; what it costs the loser stated
Background sync: <ordered drain; server dedups on client-id (no duplicate creates);
  partial-failure per-write; backoff; transport → realtime-subscription-architect>
Reconciliation: <sync cursor; pull-since; merge; integrity (no dup creates, no
  resurrected deletes, tombstones); long-offline catch-up>
Boundaries:     offline/rollback UX STATES → edge-state-ux-designer;
  server/distributed cache → caching-strategy-designer;
  live online push → realtime-subscription-architect
Open questions / risks: <each with risk-if-wrong / who answers>
```

## Validation Checklist

- [ ] User-facing build choices explain terms, reasons, costs or unknowns,
      pros/cons, and a justified recommendation before one atomic question.
- [ ] The offline surface is scoped per operation with conflict risk stated;
      not everything is made offline by reflex.
- [ ] The write queue is durable (survives restart), ordered, scoped/encrypted,
      and each write carries a client-generated idempotency id and a base
      version.
- [ ] Optimistic changes are always eventually confirmed or rolled back —
      none left on screen as saved after a server reject.
- [ ] Conflict detection exists via an explicit versioning mechanism; there is
      no silent last-writer-clobbers path.
- [ ] The conflict-resolution policy is chosen per data type with its cost to
      the loser stated; any discard (e.g. LWW) is acknowledged, never silent.
- [ ] Background sync dedups on the client-generated id so a retried sync
      never creates duplicates, and handles partial-failure per write.
- [ ] Reconciliation converges to server truth with a cursor and verifies
      integrity (no duplicate creates, no resurrected deletes, tombstones).
- [ ] UX states, server caching, and live online push are deferred to their
      owning skills.

## Gotchas

- Silent last-write-wins is the offline-first data-loss classic: two people
  edit offline, whoever syncs last wins, the other's work vanishes with no
  trace. LWW is a choice with a victim — acknowledge the discard or pick
  another policy.
- No idempotency id on queued writes means a retried sync creates duplicates:
  the create succeeded server-side, the ack was lost, the client retries, and
  now there are two. The client-generated id is what the server dedups on.
- An optimistic update with no rollback path strands rejected writes on screen
  as if saved; the user edits, sees success, and the change never persisted.
- Conflict resolution without version detection is not resolution — it is
  overwriting; you cannot resolve a conflict you cannot detect.
- CRDTs are not free magic: they add real size and complexity and change the
  data model. Reach for them for genuinely collaborative concurrent editing,
  not for a single-user notes app.
- A long-offline device that only ever does incremental sync can miss a
  server-side compaction/retention boundary and desync; design the full-
  refresh catch-up path.
- Deletes need tombstones: without them, a record deleted on the server
  resurrects from a still-offline device's local copy on next sync.
- Encrypting the local store is not optional for tenant data on a device that
  can be lost or stolen — offline data at rest is a real attack surface.

## Stop Conditions

- The chosen conflict strategy would silently discard user data (e.g. blanket
  last-write-wins on high-stakes, co-edited records) → STOP and surface the
  data-loss consequence; require an acknowledged policy (manual/merge) for
  that data rather than shipping a silent clobber.
- The server write path cannot accept a client-generated id / cannot dedup, or
  is non-idempotent → the sync engine cannot prevent duplicates; flag the
  server-side prerequisite (route to `command-gateway-architect`) before
  promising duplicate-free sync.
- Full offline is demanded for large, shared, frequently co-edited data where
  the device cannot hold the working set or conflicts would be constant →
  present the honest cost and the alternatives (online-required, partial
  offline) and stop for a human scope decision.
- Asked to build/run the sync against live data or apply a bulk reconciliation
  to production → this skill DESIGNS; executing a reconciliation/backfill
  against production follows the repo's approval path.

## Supporting Files

- `evals/evals.json` — behavior cases: the offline-layer design, the
  conflict-resolution edge, the silent-data-loss (LWW) refusal, and the
  live-online-push non-trigger.
- `evals/trigger-evals.json` — discrimination against `edge-state-ux-designer`
  (UX states vs sync engine), `caching-strategy-designer` (server cache vs
  client offline store), and `realtime-subscription-architect` (live online
  push vs offline sync — a boundary both skills' evals test).
- No `references/` — the queue/optimistic/conflict/reconciliation procedure
  above is complete; detail lives in the produced artifacts.