Keep the unwind docs and rebuild-graph.json fresh across a long migration
without re-unwinding everything. The deterministic scan fingerprints every
file; a refresh re-analyzes only the layers whose source actually changed and
flags previously-documented items whose source changed structurally as stale.
Requires: a prior full run (so docs/unwind/.cache/meta.json baseline + layer
docs + coverage/ exist).
Produces: updated layer docs, refreshed coverage/, and a regenerated
rebuild-graph.json with coverage: "stale" / rebuildStatus: "needs-recheck"
on changed contracts.
Graceful fallback: if
@unwind/core/Node/pnpm is unavailable, skip the deterministic steps and fall back to the legacyunwind:uw-analyzeRefresh Mode (re-run specialists with previous docs as context).
The Process
Step 1: Detect changes (deterministic)
Run change detection against the baseline. Order matters — this must run before re-scanning, so the baseline still reflects the last analyzed state.
# Locate the installed Unwind plugin, then load the core helper.
# $0/BASH_SOURCE are unreliable under `bash -c`, so glob the install cache.
UNWIND_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${UNWIND_PLUGIN_ROOT:-}}"
[ -f "$UNWIND_PLUGIN_ROOT/skills/scripts/_resolve-plugin-root.sh" ] || \
UNWIND_PLUGIN_ROOT="$(ls -dt "$HOME"/.claude/plugins/cache/*/unwind/*/ 2>/dev/null | head -1)"
source "${UNWIND_PLUGIN_ROOT%/}/skills/scripts/_resolve-plugin-root.sh"
ensure_unwind_core || { echo "core unavailable — using legacy refresh"; }
node "$UNWIND_PLUGIN_ROOT/skills/scripts/detect-changes.mjs" "$(pwd)"
This writes docs/unwind/.cache/changes.json:
structural/added/removed— files whose contract surface movedcosmetic— body/comment-only edits (docs stay valid; no re-analysis)affectedLayers— the only layers that need re-analysisstaleItems— documented item ids whose source changed structurallynewItems— item ids in newly-added files (become gaps after verify)
If structural, added, and removed are all empty → nothing to do; the
docs and graph remain valid. Stop here.
Step 2: Refresh the baseline scan
Re-run the scan to refresh scan-manifest.json + the meta.json baseline so
item ids match the current code:
node "$UNWIND_PLUGIN_ROOT/skills/scripts/scan.mjs" "$(pwd)"
node "$UNWIND_PLUGIN_ROOT/skills/scripts/seed-layers.mjs" "$(pwd)"
Step 3: Re-analyze ONLY the affected layers
For each layer in changes.affectedLayers, dispatch the matching
unwind:analyzing-* specialist (see unwind:uw-analyze for dispatch
mechanics), seeded with docs/unwind/.cache/seeds/{layer}.json and the existing
layer docs as context. Instruct it to:
- document any new items (in
changes.newItems), - re-confirm any stale items (in
changes.staleItems) — the signature moved, - remove docs for items in
changes.removedfiles that no longer exist.
Do not touch layers absent from affectedLayers.
Step 4: Verify + complete + regenerate the graph
node "$UNWIND_PLUGIN_ROOT/skills/scripts/verify-coverage.mjs" "$(pwd)"
# (loop verify -> unwind:uw-complete until affected layers are 100%)
node "$UNWIND_PLUGIN_ROOT/skills/scripts/build-graph.mjs" "$(pwd)"
build-graph reads changes.json and marks still-documented-but-changed nodes
coverage: "stale"; any done/verified contract whose source changed
structurally flips to rebuildStatus: "needs-recheck" (human-set progress in
rebuild-progress.json is otherwise preserved).
Step 4b: Re-check grill findings (only if a grill has run)
ls docs/unwind/.cache/grill-findings.json >/dev/null 2>&1 && echo "grill findings exist"
Each finding records the contentHash of the file it was evidenced against. When
that file's hash has moved, the finding is about code that no longer exists —
either it was fixed, or the quote is now wrong. Do not keep asserting it.
For every finding whose contentHash no longer matches the current manifest:
- Mark it
"stale": trueingrill-findings.json. - If it is still open, remove its block from the questionnaire under
docs/unwind/questions/— asking a domain expert about deleted code wastes the one thing you can't get more of, which is their willingness to answer. - If it was already answered, leave the verdict alone (the decision stands) but note the drift so the next grill re-evidences it.
Then re-run /uw-grill if the changed layers need fresh findings.
Step 5: Report
Summarize: layers re-analyzed, items added/removed, stale items resolved, and
the new coverage %. Point to docs/unwind/rebuild-graph.json for the dashboard.
Why incremental
A full unwind re-runs every specialist over every file. A refresh skips the deterministic re-scan's cosmetic churn and only pays for LLM analysis on layers that actually changed — turning the unwind spec into a living document that tracks the codebase across months of migration work.