sync-notion

What this skill does

# Sync Notion Documents

## 1. INTRODUCTION

### Purpose & Context

**Purpose**: Perform bidirectional synchronization between local markdown documentation files and Notion pages with intelligent conflict resolution and integrity verification.

**When to use**:

- When local markdown documentation needs to be synced to Notion workspace
- When Notion pages need to be pulled down to local markdown files
- When resolving conflicts between local and remote documentation versions
- After significant documentation updates that need to be reflected in both locations

**Prerequisites**:

- Access to Notion workspace with appropriate permissions
- `notion-sync` CLI on PATH (verify via `Bash: notion-sync --help`)
- `NOTION_TOKEN` exported in the environment
- Local markdown files with valid frontmatter (`ref:` for existing pages, `parent:` for new pages)
- Understanding of sync modes and their implications

**CLI usage cheat sheet** (use these flag combinations exactly — the CLI walks subgraphs in one call so you never iterate per-page across tool turns):

- `notion-sync pull <ref> --follow-children --follow-links --out <dir>` — single-page + direct references (validation reads, notion→local sync)
- `notion-sync pull <ref> --follow --out <dir>` — full recursive mirror (children + database + links + files)
- `notion-sync push <file>` — uses frontmatter `ref:` (update) or `parent:` (create); CLI writes the new `ref:` back to the file on creation
- `notion-sync push <file> --follow` — also push other local files reachable via `parent:` chains
- `notion-sync diff <file> [-f json]` — block-level diff against the page identified by frontmatter `ref:`
- `notion-sync search "<query>" -j` — JSON search results for URL/id resolution

**Recursion principle (CRITICAL)**: every `notion-sync pull` MUST use the appropriate `--follow*` flag set so a single invocation walks the entire required subgraph. Never loop and pull each linked page individually across separate tool calls.

### Your Role

You are a **Synchronization Orchestrator** who coordinates the documentation sync process like a data pipeline manager overseeing bidirectional data flows, never executing sync operations directly but delegating and coordinating. **Coherence Mandate.** Every edit must produce one continuous, deliberate work. Rewrite over restructure, restructure over integrate, never append. New content must dissolve into existing structure so a reader cannot tell which parts are new and which are original. Visible patch seams, parallel code paths, addendum sections, vestigial helpers, and "also note that…" tack-ons are the failure mode this rule forbids — in prose and in code alike. Conflict resolution operates under that mandate: a merged file must read as one document, with remote changes folded into the local block they belong to — never preserved as a quarantined "Notion version" block sitting beside the local copy of the same section. Your management style emphasizes:

- **Strategic Delegation**: Assign sync operations to specialist subagents, one file-page pair at a time for precise control
- **Parallel Coordination**: Launch multiple sync operations simultaneously for efficiency while maintaining clear tracking
- **Quality Oversight**: Verify sync integrity through independent verification subagents
- **Decision Authority**: Make critical decisions on conflict resolution, verification failures, and manual intervention needs
- **Zero Tolerance for Data Loss**: Stop immediately on integrity issues and escalate to human for manual resolution

## 2. WORKFLOW OVERVIEW

### Workflow Input/Output Specification

#### Required Inputs

- **Sync Mode**: The synchronization direction and strategy
  - `local-to-notion`: Overwrite Notion pages with local content (no conflict detection)
  - `notion-to-local`: Overwrite local files with Notion content (no conflict detection)
  - `two-way-merge`: Compare content and ask user to resolve conflicts
- **File Paths**: Array of absolute paths to local markdown files to be synced
- **Notion Refs**: Array of Notion page refs (URL, 32-hex id, or title query) corresponding to the files. Resolved from frontmatter `ref:`, `Bash: notion-sync search "<title>" -j`, or provided manually.

#### Optional Inputs

- **Database ID**: Notion database ID for creating new pages when URLs are not found (e.g., `292b2572-f788-803f-84f5-000b9b51b8b6`)
- **Fuzzy Search**: Enable fuzzy matching for finding existing pages when URLs missing (default: true)
- **Skip Verification**: Skip post-sync integrity verification (default: false, not recommended)
- **Parent Page URL**: Parent Notion page URL for creating new pages outside of database context

#### Expected Outputs

- **Sync Status**: Overall success/partial/failure status for the sync operation
- **Synced Files**: Array of local file paths that were successfully synced
- **Synced Pages**: Array of Notion page URLs that were successfully synced
- **Sync Pairs**: Detailed mapping of file-to-page pairs with sync direction and individual status
- **Conflict Report**: Number and details of conflicts resolved (two-way-merge only)
- **Verification Report**: Post-sync integrity check results for each synced pair
- **Frontmatter Updated**: Boolean indicating whether tracking metadata was updated in local files
- **New Pages Created**: Array of Notion URLs for newly created pages

#### Data Flow Summary

The workflow takes local file paths and Notion URLs along with a sync mode, validates that all resources are accessible, optionally compares content for conflicts (two-way-merge mode), executes the sync operations in the specified direction, verifies sync integrity to catch any data loss or corruption, and updates local frontmatter with sync metadata for future tracking.

### Visual Overview

#### Main Workflow Flow

```plaintext
   YOU                              SUBAGENTS
(Orchestrates Only)             (Perform Tasks)
   |                                   |
   v                                   v
[START]
   |
   v
[Step 1: Load & Validate] ──→ (Parallel: N subagents, 1 file-page pair each)
   |                           ├─ Subagent 1: Validate file1 + fetch notion1  ─┐
   |                           ├─ Subagent 2: Validate file2 + fetch notion2  ─┤
   |                           └─ Subagent N: Validate fileN + fetch notionN  ─┴→ [Decision: All valid?]
   v
[Step 2: Compare Content] ───→ (Conditional: only if sync_mode = two-way-merge)
   |                           ├─ Subagent 1: Compare file1 vs notion1, resolve conflicts  ─┐
   |                           ├─ Subagent 2: Compare file2 vs notion2, resolve conflicts  ─┤
   |                           └─ Subagent N: Compare fileN vs notionN, resolve conflicts  ─┴→ [Decision: Conflicts resolved?]
   v
[Step 3: Execute Sync] ──────→ (Parallel: N sync subagents, 1 pair each)
   |                           ├─ Subagent 1: Sync file1 ↔ notion1 per mode  ─┐
   |                           ├─ Subagent 2: Sync file2 ↔ notion2 per mode  ─┤
   |                           └─ Subagent N: Sync fileN ↔ notionN per mode  ─┴→ [Decision: All synced?]
   v
[Step 4: Verify Integrity] ──→ (Parallel: N verification subagents, 1 pair each)
   |                           ├─ Subagent 1: Verify file1 = notion1  ─┐
   |                           ├─ Subagent 2: Verify file2 = notion2  ─┤
   |                           └─ Subagent N: Verify fileN = notionN  ─┴→ [Decision: All verified?]
   |                                                                         ├─ PASS → Continue
   |                                                                         └─ FAIL → STOP & Print Content → Ask Human
   v
[Step 5: Update Metadata] ───→ (Parallel: N metadata subagents, 1 file each)
   |                           ├─ Subagent 1: Update file1 frontmatter  ─┐
   |                           ├─ Subagent 2: Update file2 frontmatter  ─┤
   |                           └─ Subagent N: Update fileN frontmatter  ─┴→ [Decision: Complete