Uw Graph

Emitting the Rebuild Graph

Purpose: Export docs/unwind/rebuild-graph.json — the joined knowledge-graph artifact that the Unwind dashboard renders. It fuses the deterministic scan, the coverage diff, and the layer documentation into a single graph where every node carries a rebuild block.

> When do you actually need this skill? Only to produce the JSON without > launching a server — a static deploy (e.g. the live demo), CI, sharing, or > diffing the artifact. For interactive viewing you don't need it: unwind:uw-dashboard > regenerates the graph itself before launching. This is an optional export, not a > required pipeline gate.

Output: docs/unwind/rebuild-graph.json

> Two graphs — don't confuse them. scan-manifest.json (built by uw-scan) is > the ground truth — the file/symbol/import graph that drives seeds, the coverage > diff, and completeness; the analysis skills read it, never this file. > rebuild-graph.json (this skill's output) is a refreshable projection of > manifest + coverage + docs that only the dashboard reads — nothing upstream > reads it back. So it sits at the end of the linear pass (where it's richest), but > it does not drive analysis and is not rigidly last: you can build it right > after uw-scan for a structural view (everything scanned) and re-run it after any > phase to refresh. Safe to regenerate anytime.

> Graceful fallback: if Node/pnpm or @unwind/core are unavailable, or if no > scan-manifest.json exists yet, the script exits non-zero with a clear message. > Run uw-scan (scan) first; the graph is an enhancement, never a hard dependency.

Inputs (all deterministic)

| Input | Source | Contributes | |-------|--------|-------------| | Structure | docs/unwind/.cache/scan-manifest.json | file/function/class/table/endpoint nodes + import edges | | Coverage | docs/unwind/.cache/coverage/{layer}.json | rebuild.coverage (scanned / documented / verified) | | Layer docs | docs/unwind/layers/**/*.md | rebuild.priority (MUST/SHOULD/DON'T) + rebuild.docRef | | Progress overlay (optional) | docs/unwind/.cache/rebuild-progress.json | rebuild.rebuildStatus (human-maintained, never clobbered) |

The first three are produced by the uw-scan and uw-verify skills. Coverage and docs are optional — without them the graph still builds with every node marked scanned / not-started.

Process

Step 1: Build the graph

# 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 — skip rebuild graph"; exit 0; }
node "$UNWIND_PLUGIN_ROOT/skills/scripts/build-graph.mjs" "$(pwd)"

The script:

1. Loads the manifest (the candidate id scheme guarantees nodes join 1:1 with the

coverage reports).

1. Builds nodes (files + their symbols) and edges (contains, imports,

tested_by by path convention).

1. Enriches each node's rebuild block:

• coverage — covered-by-anchor-id → verified, covered-by-name → documented,

missing → scanned, DON'T-tagged → excluded.

• priority + docRef — parsed from the [MUST]/[SHOULD]/[DON'T] tag and the

markdown file the item was documented in.

• contractKind — db-table / api-endpoint / event-schema / formula.
• rebuildStatus — merged from rebuild-progress.json if present, else derived

from coverage. The overlay always wins, so regeneration never erases human progress.

1. Validates with validateRebuildGraph (unique ids, no dangling edges, every node

has an explicit priority), then writes the file.

It prints a summary: node / edge / layer counts and a coverage breakdown.

Step 2: Report

Relay the printed summary (node / edge / layer counts, coverage breakdown) and point the user at docs/unwind/rebuild-graph.json. Since this is the artifact-export path, mention the likely reason they ran it (static deploy / CI / sharing).

If they actually wanted to view the graph, point them at unwind:uw-dashboard (which would have built it for them) rather than treating this as a required step.

> Pipeline: scan → analyze → plan → dashboard. uw-graph is an optional > export off to the side — the dashboard builds the graph itself.

The rebuild block

{
  "priority": "MUST",            // MUST | SHOULD | DON'T | null
  "contractKind": "db-table",    // db-table | api-endpoint | event-schema | formula | null
  "coverage": "verified",        // scanned | documented | verified | excluded | stale
  "docRef": "docs/unwind/layers/database/tables.md",
  "rebuildStatus": "verified"    // not-started | in-progress | done | verified
}

Re-running

Safe to re-run after every scan or doc change. To record manual rebuild progress, write docs/unwind/.cache/rebuild-progress.json keyed by node id, e.g.:

{ "table:src/db/schema.ts:users": { "rebuildStatus": "in-progress" } }

Source & license

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

• Author: nearform
• Source: nearform/unwind
• License: MIT

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