---
name: sync-and-reconcile
description: Use when a Remix-bound repo needs to be aligned with remote app state and you must choose between sync and reconcile safely.
---

# Sync And Reconcile

Use this skill when the user asks to sync, update, or recover alignment between a local repo and its Remix app state.

Mental model:

- `remix_collab_sync_*` is for pulling Remix-known app state into the local repo when fast-forward sync is possible.
- `remix_collab_reconcile_*` is for cases where local history exists that Remix cannot fast-forward from.
- `remix_collab_sync_upstream` is for bringing new upstream app changes into a remix.
- `remix_collab_record_turn` is not a sync tool. It records a no-diff completed turn and does not create a commit.

Workflow:

1. Start with `remix_collab_status`.
2. If sync looks available, use `remix_collab_sync_preview`.
3. Only use `remix_collab_sync_apply` after preview indicates the fast-forward path is appropriate.
4. If sync is not available because history diverged, use `remix_collab_reconcile_preview`.
5. Only use `remix_collab_reconcile_apply` when reconcile is clearly required and the user understands the risk.

Important rules:

- Prefer sync over reconcile whenever sync is available.
- Reconcile is a last-resort operation because it rewrites local history and creates backup branches.
- Explain local mutation risk before any apply step.
- For remix repos, use `remix_collab_sync_upstream` when the task is specifically about bringing upstream changes into the remix rather than aligning the local repo with its current Remix app head.
- Do not treat no-diff turn recording as a substitute for sync, reconcile, or upstream sync.
