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 `` 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 Pipeline: scan → analyze → verify ✓** → complete → plan → dashboard.

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.