nearform/unwind/uw-verify

Verifying Layer Documentation

Purpose: Detect gaps between documentation and source code. Output is a work list for the next skill to fix.

This is now a deterministic check. Completeness is verified by set arithmetic (manifest − docs), not a subjective LLM comparison. The scanner already knows the ground-truth set of items per layer; this skill diffs that against what the docs actually contain (matched by anchor id, then by name).

Output:

• docs/unwind/.cache/coverage/{layer}.json - per-layer coverage report
• docs/unwind/layers/{layer}/gaps.md - missing items work list (only when gaps exist)

Process

Step 1: Run the Coverage Verifier

# 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 LLM gap detection"
node "$UNWIND_PLUGIN_ROOT/skills/scripts/verify-coverage.mjs" "$(pwd)"

The script:

1. Loads docs/unwind/.cache/scan-manifest.json (the ground-truth candidate set).
2. Reads every section .md under each docs/unwind/layers/{layer}/ folder and

extracts documented item ids (from <!-- id: ... --> anchors, then fuzzy by name).

1. Diffs them: missing = in source, not in docs; extra = documented but

not in scan (flagged for review — may be dynamic or stale).

1. Writes coverage/{layer}.json and a gaps.md work list for any layer with

missing items.

Step 2: Summarize

Report the per-layer coverage table the script prints (covered/total = pct%), and point the user/orchestrator at the generated gaps.md files. Then hand off to uw-complete to fill them.

Output Format (generated gaps.md)

# {layer} Documentation Gaps
 
> Generated by verify-coverage. Coverage: 36/37 (97.3%).
 
## Missing Items
 
### users
-**Type:** table
-**Location:** src/db/schema.ts:12-34
-**Id:** `table:src/db/schema.ts:users`

uw-complete reads this verbatim, documents each item under the correct section using the anchor-id heading format, and deletes gaps.md.

Legacy Fallback (no @unwind/core)

When the deterministic core is unavailable (no Node/pnpm, or build failed), fall back to the subjective comparison: for each layer, read the docs and the source entry points from architecture.md, build the two item lists by hand, and write the gaps the LLM finds to docs/unwind/layers/{layer}/gaps.md in the same format. This is slower and not reproducible — it exists only so the plugin still functions without the deterministic engine.

Next Step — continue or pause?

The branch depends on the coverage table just printed:

• Any layer < 100% (gaps.md written) → next is unwind:uw-complete to fill them.
• Every layer 100% → analysis is done → next is unwind:uw-plan.

Use AskUserQuestion to confirm:

• Continue (recommended) — invoke unwind:uw-complete (gaps remain) or

unwind:uw-plan (100%).

• Pause here — stop and resume later.

Act in the same turn; if they pause, tell them how to resume: "Run `unwind:uw-complete` (type `/uw-complete`) to fill gaps, or `unwind:uw-plan` if coverage is already 100%."

Pipeline: scan → analyze → verify ✓ → complete → grill → plan → dashboard.