Skip to content
cccskills
FreePublished on GitHub

offline-sync

Use when a screen must work without network or a mutation must survive a lost connection - local storage choice, the outbox pattern with idempotency keys, background replay, and how to test it with a fake clock and fake network.

The English summary is being prepared. Showing the original description.

See how to install

Files included (1)

  • SKILL.md3.4 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

Offline and Sync

Overview

Treat "offline" as a normal state, not an error condition: a screen that only works with a live connection is a defect on mobile. The hard part isn't detecting offline — it's making a queued mutation replay exactly once and keeping the UI honest about what's actually saved.

Local store

Follow the repo's existing choice (drift/sqflite for Flutter, Room for Android, SwiftData/Core Data for iOS) — don't introduce a second local-storage mechanism alongside one that's already there.

Outbox pattern

  • Queue mutations in a local outbox table when offline; replay on reconnect.
  • Every queued mutation carries a client-generated idempotency key, sent with the eventual request, so a retried replay (after a crash mid-sync, or a flaky connection that "succeeded" without the ack arriving) is deduplicated server-side instead of double-applied.
  • Connectivity plugins (connectivity_plus and equivalents) report the state of the network interface, not whether the server is actually reachable — treat the server's response as the source of truth for whether a request succeeded, not the interface state alone.

Background replay

  • Android: WorkManager (native) or the workmanager plugin (Flutter) for replay that must survive the app being backgrounded or killed.
  • iOS: BGTaskScheduler for background replay — register and schedule it, and test on-device since the simulator's background scheduling is unreliable.

UI honesty

Show sync status explicitly per item — pending / syncing / failed — never render an unsynced change as if it were already saved. A spinner that never resolves is worse than an honest "failed, tap to retry."

Conflicts

Pick one conflict rule per data type (last-write-wins, or an explicit user choice when both sides changed) and write it down in the task — don't leave it implicit in the code for the next person to infer.

Reads degrade gracefully

Cached data with a staleness indicator beats a spinner that never resolves — show what you have, mark it as possibly stale, and update when the network returns.

Testing

  • Unit tests: a fake clock and a fake network/repository to drive queue → replay → ack deterministically, including the "replay happens twice" case to prove the idempotency key actually dedupes.
  • On a local emulator: adb shell cmd connectivity airplane-mode enable / disable to exercise a real reconnect, not just a mocked one.

Common Mistakes

  • A screen that shows a blank/error state the instant the network drops, instead of cached data.
  • A queued mutation with no idempotency key — a retried replay double-applies it.
  • Trusting the connectivity plugin's "online" state as proof a request will succeed.
  • A sync-status UI that doesn't distinguish pending from failed.
  • Only testing airplane-mode-on; never testing the reconnect/replay path.

Red Flags

  • A mutation sent to the server with no client-generated key the server can dedupe on.
  • "It works offline" verified only by reading the code, not by actually toggling airplane mode or a fake network.
  • No written conflict rule for a data type that can be edited from two places.

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Comments are published right away. Do not include personal information such as email addresses or phone numbers. Up to 2 URLs.

0 / 1,000 characters

This form is protected by reCAPTCHA, and the Google Privacy Policy and Terms of Service apply.

More skills from this repository

Use when writing acceptance criteria for a task - express each as an observable Given/When/Then that QA can execute, including negative cases

The English summary is being prepared. Showing the original description.

makifbaysal/tasktrooper117Updated Oct 18, 2026

Use when the diff adds or changes an endpoint, resolver, RPC, job or query that takes an object id, a role check, a request binding or a tenant filter - BOLA/IDOR, function-level authorization, mass assignment and tenant scoping

The English summary is being prepared. Showing the original description.

makifbaysal/tasktrooper117Updated Oct 18, 2026

Use on every UI change - semantic HTML, labels for controls, keyboard-navigable dialogs/menus, visible focus, and never color as the only signal

The English summary is being prepared. Showing the original description.

makifbaysal/tasktrooper117Updated Oct 18, 2026

Use when a task changes any screen, form, dialog, menu or control - Lighthouse/axe scan of the changed screens, a keyboard walk, and the thresholds that fail a task

The English summary is being prepared. Showing the original description.

makifbaysal/tasktrooper117Updated Oct 18, 2026

How to work a task returned with review, QA or UAT findings. Use when a task is in need_revision or PR review comments are in your context.

The English summary is being prepared. Showing the original description.

makifbaysal/tasktrooper117Updated Oct 18, 2026

Use when the repository keeps its alerting in code, or a person asks for alerts outside TaskTrooper - PrometheusRule YAML, a Cloud Monitoring alert policy in Terraform, a Datadog monitor, each routed to TaskTrooper's alert ingest URL so it opens an incident here

The English summary is being prepared. Showing the original description.

makifbaysal/tasktrooper117Updated Oct 18, 2026

See all skills by makifbaysal

Report a problem with this skill