## TL;DR

Sync on the sort key the API actually uses (updated_at here), not the one you assumed. Records that get edited after creation move position under updated_at ordering, so a created_at watermark skips them. Change the watermark, backfill the gap, done.

```
agent assumed the list endpoint sorted by created_at  -  the API sorts by updated_at and the incremental sync missed new records
```

## Steps

1. Verify the real sort. Page the list endpoint and compare the order of returned records against their created and updated timestamps. Expected: you can state the actual sort key and direction with evidence.

2. Change the sync to filter and watermark on updated_at (or whatever the API sorts by). Expected: the query parameter and the stored cursor both use the real key.

3. Backfill the gap: run one historical sync covering the period the broken sync ran, and reconcile against your store. Expected: the previously missed records appear and counts match.

4. Handle updates as upserts, not inserts, since updated_at ordering means you will legitimately re-see edited records. Expected: reprocessing an edited record does not create a duplicate.

5. Watch one full sync cycle and diff the synced set against a full list pull. Expected: zero missing and zero duplicated records.

## Use this when

- An incremental sync misses records that were created earlier but edited later.
- The API docs are vague about sort order and the agent picked created_at by convention.
- Record counts in your store drift below the provider's counts over time.

## Not for this skill when

- Records are missing because pagination broke - see the pagination skills.
- The API genuinely sorts by created_at - then the bug is elsewhere.
- You need deleted records too - that needs a separate tombstone or audit endpoint.

## Variant phrasings

- incremental sync missed records because API sorts by updated_at not created_at
- sync watermark on created time skipped updated records
- list endpoint ordering assumption broke incremental sync

## Why it happens

created_at ordering is the intuitive default, so agents reach for it without checking. But providers sort by updated_at because their own UIs want "recently active" first. Any record edited after creation then sorts ahead of newer-but-untouched records, and a created_at watermark walks right past it.

## Edge cases

- updated_at and created_at can be identical for never-edited records, which hides the bug in small test datasets.
- Some APIs let you pick the sort via a parameter; if so, request the key your sync is built for explicitly.
- Ties on identical timestamps need a secondary stable key (id) or records can be skipped at page boundaries.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_LE2nWL_fYePFuf94JUQ9KQ