---
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.

This skill is only about repository alignment. Use the general collaboration workflow skill for recording, memory-first history routing, and other bound-repo rules.

Mental model:

- `remix_collab_sync_*` is for pulling Remix-known app state into the local repo when fast-forward sync is possible (i.e. `recommendedAction: pull`, `repoState: server_only_changed`).
- `remix_collab_reconcile_*` is for the rare case where both the local workspace and the server lane changed since the last agreed baseline (i.e. `recommendedAction: reconcile`, `repoState: both_changed`).
- `remix_collab_sync_upstream` is for bringing new upstream app changes into a remix.
- Automatic hook recording is not a sync tool. It records the completed turn, but it does not replace sync, reconcile, or upstream-sync workflows.
- Missing local revision baselines route through init/sync; if status reports `local_only_changed` (or `recommendedAction: record`), routine completed-turn hook recording is the answer, never reconcile.

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.
