sync-validate

Review Notion worker sync code for pagination, cursor, and state bugs.

Updated Jul 31, 2026
One-click install
npx skills add https://github.com/Duckshot-Productions/ntn-worker --skill sync-validate-duckshot-productions
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: sync-validate
Source: https://github.com/Duckshot-Productions/ntn-worker/tree/main/.agents/skills/sync-validate
Command: npx skills add https://github.com/Duckshot-Productions/ntn-worker --skill sync-validate-duckshot-productions

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Sync capabilities in Notion workers can silently lose data or loop forever due to subtle bugs in cursor advancement, pagination termination, and backfill-to-delta transitions. This Skill audits sync code against a structured checklist to catch these issues before deployment. ## Core Features & Use Cases - Critical Bug Detection: Identifies infinite pagination loops, non-advancing cursors, missing first-run state handling, and oversized batches that will break a sync in production. - Bi-Modal Correctness Review: Validates backfill-to-delta transitions, overlap windows, and discriminated state unions for incremental syncs. - Data Quality Warnings: Flags missing consistency buffers, timestamp tie-breaking issues, unhandled deletions, hardcoded secrets, and missing fetch error handling. - Use Case: After scaffolding a new sync with the /sync command, run this review to verify the generated code handles cursor state, pagination termination, and deletion markers correctly before deploying. ## Quick Start Review the sync capabilities in src/index.ts for common bugs and report findings grouped by severity.

Frequently Asked Questions about sync-validate

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review a Notion worker sync for bugs?▼

Run this review against src/index.ts to check each sync against a 14-point checklist covering pagination termination, cursor advancement, state handling, and deletion markers. Findings are grouped by severity with concrete code fixes.

Why does my incremental sync loop forever or skip records?▼

Infinite loops happen when nextState never advances or hasMore never becomes false. Skipped records usually come from missing overlap windows during backfill-to-delta transitions or cursors without consistency buffers on eventually consistent APIs.

When should a sync use incremental mode instead of replace mode?▼

Use incremental mode when the source API supports change tracking such as updated_at filters or event feeds. Replace mode re-fetches everything each cycle, which wastes requests and can miss deletions handled differently between modes.

How should deletions be handled in an incremental sync?▼

Check whether the source API exposes a delete signal such as an audit log or archived filter. If it does, emit delete markers with the record key; if the signal lives on a separate endpoint, alternate streams at cycle boundaries using the flip-flop pattern.

What are the limitations of this sync review?▼

The review is a static checklist-based audit of sync code and does not execute the sync against live APIs. It cannot detect runtime issues like actual rate limiting behavior or API-specific response quirks beyond what is visible in the code.