refresh-snapshots

name	refresh-snapshots
description	Use to re-run the harness's snapshot/mirror flows so installed state matches version-controlled source — skill symlinks into ~/.claude, ~/.codex, ~/.gemini tool homes, git submodule pointers, and shell plugin checkouts. Use after restructuring skills, when links look stale or broken, or on a periodic freshness pass. Triggers: "refresh snapshots", "relink skills", "update submodules", "my installed skills are stale".
metadata	{"owner":"tze","authors":["tze","Claude Fable 5"],"status":"active","last_reviewed":"2026-06-12"}
compatibility	Assumes ~/.dotfiles with bootstrap.sh and the ai-bootstrap submodule; flows are idempotent and safe to re-run.

Refresh Snapshots

Several pieces of installed state are snapshots of version-controlled source: symlink trees generated by bootstrap.sh, submodule checkouts pinned to a recorded commit, plugin clones. They go stale silently when the source moves. Every flow here is idempotent — re-running a fresh one is a cheap no-op.

Health check without refreshing

To answer "is my harness healthy" without changing anything, run the doctor — it executes every flow's verify check (broken links, submodule drift, shell load, bd doctor, required binaries) as one pass/fail report:

bash <this-subskill>/scripts/harness_doctor.sh

Keep scripts/harness_doctor.sh in sync when adding a flow to the catalog.

Workflow

1. Read the flow catalog: references/snapshot-flows.md — it lists each snapshot, its refresh command, and its verification check.
2. Run the refresh for the flows the task needs (or all of them on a periodic pass), then run each flow's verification and report refreshed/already-fresh/failed per flow.
3. If a refresh changed git state (e.g. a submodule pointer moved), commit it per the owning repo's conventions — pointer bumps in ~/.dotfiles use the existing Update ai-bootstrap pointer message style.
4. Write back (maintenance contract): if you discover a snapshot flow not in the catalog — any script that copies or links version-controlled content into a runtime location — append it to references/snapshot-flows.md in the same change.

Boundaries

• Refreshing a checkout to its recorded pointer (git submodule update) is always safe; advancing a pointer (--remote) changes behavior — do it only when the task asks for updates, and report what moved.
• If a verification fails after refresh (broken links remain, a skill vanished from a tool home), stop and diagnose before re-running — the flows are idempotent, so a second blind run cannot fix a real failure.
• Some machines symlink tool homes wholesale (~/.claude → ai-bootstrap/.claude); others may copy. Confirm with ls -ld ~/.claude before reasoning about which flow applies.