# 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

- **Type:** Skill
- **Install:** `agentstack add skill-nearform-unwind-uw-refresh`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nearform](https://agentstack.voostack.com/s/nearform)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nearform](https://github.com/nearform)
- **Source:** https://github.com/nearform/unwind/tree/main/skills/uw-refresh

## Install

```sh
agentstack add skill-nearform-unwind-uw-refresh
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nearform](https://github.com/nearform)
- **Source:** [nearform/unwind](https://github.com/nearform/unwind)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-nearform-unwind-uw-refresh
- Seller: https://agentstack.voostack.com/s/nearform
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.