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-dashboardregenerates 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 byuw-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 afteruw-scanfor a structural view (everythingscanned) and re-run it after any phase to refresh. Safe to regenerate anytime.
Graceful fallback: if Node/pnpm or
@unwind/coreare unavailable, or if noscan-manifest.jsonexists yet, the script exits non-zero with a clear message. Runuw-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:
- Loads the manifest (the candidate id scheme guarantees nodes join 1:1 with the coverage reports).
- Builds nodes (files + their symbols) and edges (
contains,imports,tested_byby path convention). - Enriches each node's
rebuildblock: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 fromrebuild-progress.jsonif present, else derived from coverage. The overlay always wins, so regeneration never erases human progress.
- Validates with
validateRebuildGraph(unique ids, no dangling edges, every node has an explicitpriority), 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 → grill → plan → dashboard.
uw-graphis 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" } }