sync-validate

Instructions

Read the sync capabilities in src/index.ts (and any imported modules). For each sync found, run through the checklist below. Report findings grouped by severity.

Before starting, read .agents/skills/sync-guide/SKILL.md for the full sync concepts reference.

Critical Issues (will break the sync or cause data loss)

1. No pagination termination: Does hasMore eventually become false? Look for: infinite loops where nextState doesn't advance, missing base cases, conditions that can never be met.

2. Cursor doesn't advance: Does nextState change between iterations? If the cursor is the same as the previous state, the sync will loop forever. Check that each execute call makes progress.

3. Missing first-run handling: When state is undefined (first run), does the code handle it gracefully? Look for: state.cursor without state?.cursor, property access on potentially undefined state.

4. Batch too large: Is the sync returning thousands of changes in one execution? Recommend batches of ~100. Large batches will fail.

5. Replace mode when API supports change tracking: If mode is replace (or unset — it defaults to replace), does the source API support updated_at filters, event feeds, or similar change tracking? If so, recommend a replace-mode backfill plus a separate incremental delta sync sharing the same database. Do not recommend switching the existing sync directly to incremental, because that loses initial-load and mark-and-sweep behavior.

6. State persistence misunderstanding: In incremental mode, the cursor never resets between cycles. The next cycle starts exactly where the last one left off. Check for code that assumes a fresh start each cycle — this will cause records to be re-fetched or skipped permanently.