uw-refresh
/uw-refresh
Use to update an existing Unwind analysis after code changes — re-analyzes only the affected layers instead of re-unwinding the whole codebase
- Author
- nearform ↗
- Repository
- unwind ↗
- Licence
- MIT
- Last repository change
- 08.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 08.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use to update an existing Unwind analysis after code changes — re-analyzes only the affected layers instead of re-unwinding the whole codebase
Original author description
Use to update an existing Unwind analysis after code changes — re-analyzes only the affected layers instead of re-unwinding the whole codebase
How it works
- The Process
- Why incremental
SKILL.md preview
---
name: uw-refresh
description: Use to update an existing Unwind analysis after code changes — re-analyzes only the affected layers instead of re-unwinding the whole codebase
allowed-tools:
- Read
- Grep
- Glob
- Bash(git:*, mkdir:*, ls:*)
- Bash(node:*)
- Bash(pnpm:*)
- Bash(source:*)
- Read(docs/unwind/.cache/**)
- Write(docs/unwind/**)
- Edit(docs/unwind/**)
- Task
---
# Refreshing Analysis (Incremental Update)
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 legacy `unwind:uw-analyze`
> Refresh 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.
```bash
# 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 moved
- `cosmetic` — body/comment-only edits (docs stay valid; no re-analysis)
- `affectedLayers` — the only layers that need re-analysis
- `staleItems` — documented item ids whose source changed structurally
- `newItems` — 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:
```bash
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.removed` files that no longer exist.
Do **not** touch layers absent from `affectedLayers`.
### Step 4: Verify + complete + regenerate the graph
```bash
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)
```bash
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": true` in `grill-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.
Versions
The database has no other skills named uw-refresh.
Database snapshot: 13.11.2026 · package version bed7cb4d83f7 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100ui4-convert-tests
Use when UI changes are complete and e2e tests need updating. Analyzes what changed in UI components and systematically finds/fixes affected tests. - 100uw-start
Start here. The entry point for reverse-engineering a codebase with Unwind — orients you, checks prerequisites, handles restart vs update, then runs the rebuild pipeline (scan → analyze → grill → plan → dashboard) with a checkpoint at each phase. Use when beginning Unwind on a… - 100uw-help
Use when starting any reverse engineering task - establishes how to find and use Unwind skills for codebase analysis, service mapping, and documentation - 100update-codebase-map
Refresh an existing .claude/.codebase-info/ map after code changes. Use for stale codebase or architecture docs; use map-codebase to create one. - 90chameleon-refresh
Use when the user explicitly invokes /chameleon-refresh to re-analyze the current repo and update the chameleon profile after drift - 100om-smart-test
Run only the tests affected by changed code. Use when the user says "run affected tests", "run smart tests", "test only what changed", "run tests for this PR", "run tests for my changes", "selective tests", or asks to run tests without running the full suite.