knowledge-gaps

Knowledge Gap Detection

Analyze the current project's dependencies against Basic Memory coverage to identify packages that should be documented but aren't. Supports npm, Rust crates, Go modules, PHP Composer, PyPI, and RubyGems.

When invoked with --stale [<ecosystem>], the skill instead runs an alternative version-drift workflow (Mode A below) that flags documented brew/npm/cask/crate/vscode/plugin notes whose recorded version has fallen behind upstream — not a coverage audit.

Edge Cases

• No manifest files found — if none of the Step 0 globs match, report "No package manifest files detected" and skip Steps 1–5. Still proceed to Steps 6–9 to check for tool manifests.
• No tool manifests found — if Steps 6 finds nothing, report "No tool manifests detected" and skip Steps 7–9. Still run Step 10 for dead wiki-links.
• Ecosystem directory missing in BM — if list_directory returns nothing for npm/, crates/, etc., treat coverage as 0 documented for that ecosystem. Do not error.
• Empty manifest — if package.json has no dependencies or devDependencies, or Cargo.toml has no [dependencies] tables, report "No dependencies found in " and skip that ecosystem.
• Brewfile with only comments or taps — if no brew "...", cask "...", or vscode "..." lines exist after filtering, report "No tools found in Brewfile".
• Workflow file with no uses: lines — if a .github/workflows/*.yml file exists but has no uses: lines matching the pattern, skip it silently.
• RETRO-*.md not committed — retro files are gitignored; find still detects them locally. This is expected behavior.
• Readwise not available — if readwise_search_highlights or reader_search_documents fails or returns no results, skip the reading- signal analysis in Step 14b and report only graph-based hub gaps in Step 15.
• bm CLI not available — if the bm project info command in Step 10 fails, skip the quick-exit gate and proceed directly with the relation index queries.
• brew CLI not available — if brew leaves in Step 7b fails (non-zero exit, command not found, or empty output on a non-macOS host), skip the Brewfile-vs-installed reconciliation silently and report brew coverage in Brewfile-only mode. This is the expected fallback for auditing a remote machine's declared deps from a different host.
• --global manifest absent — if ~/.claude/plugins/installed_plugins.json (plugins) or ~/.agents/.skill-lock.json (skills) is missing/unreadable in Step 7c, skip that population silently and note it; the other still runs. These are user-global, so a CI host without ~/.claude simply yields nothing.
• --global + --stale together — reject; they are separate modes (coverage vs drift). Run one at a time.
• --full with a scope flag — reject --full combined with any of --limit/--since/--sample ("--full can't be combined with --limit/--since/--sample — pick one"). --full is the opt-out from the scope preflight, not a narrowing flag, so pairing it with one is contradictory.
• Scope preflight is top-level-only — the --stale scope preflight (AskUserQuestion) fires only in the Mode A skill body, never inside a wave subagent. It must never migrate into references/staleness-detection.md (loaded verbatim into subagents), where AskUserQuestion auto-approves and returns empty. A sub-40 largest cohort, or any typed scope flag / --full, skips the prompt.
• recent_activity unavailable or empty (Step 10 recency-scoped sweep) — if the call errors, report "Recency sweep unavailable — could not confirm recent-note coverage" in the gap report rather than treating an empty or failed result as "zero recently active notes." If it returns zero results (no MCP error, empty list), that IS a valid clean state — distinguish the two explicitly in the report; do not conflate them.
• read_note fails mid-sweep (Step 10 recency-scoped sweep, step 3) — skip that note, name it in the report ("N of M recently-active notes could not be read — sweep is partial"), and continue with the remaining notes. Do not silently report the partial result as if it were the full recency sweep.