notion-workers: Skill for Claude Code

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 switching to incremental to avoid re-fetching everything each cycle.

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.

Structural Issues (bi-modal correctness)

1. Single-mode cursor for incremental sync: Is the sync using the same cursor strategy for both backfill and delta? Unless the API sorts by updated_at and uses an opaque cursor (where one cursor naturally serves both), the sync should have a discriminated state union with separate backfill and delta phases.