Skip to content
Skills Library
Programming · Automation

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

Repository
unwind ↗
Licence
MIT
Last repository change
08.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.10.2026, without references to retired models or APIs.

Licence

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

  1. The Process
  2. Why incremental
Original SKILL.md headings · 113 lines, 656 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.