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 reportdocs/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:
- Loads
docs/unwind/.cache/scan-manifest.json(the ground-truth candidate set). - Reads every section
.mdunder eachdocs/unwind/layers/{layer}/folder and extracts documented item ids (from<!-- id: ... -->anchors, then fuzzy by name). - Diffs them: missing = in source, not in docs; extra = documented but not in scan (flagged for review — may be dynamic or stale).
- Writes
coverage/{layer}.jsonand agaps.mdwork 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-completeto 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) orunwind: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.