kb-audit

kb-audit - Documentation Rot Detector

Scan every markdown doc in the current project, verify concrete claims against the code, and produce a single verdict note in the vault: which docs are current, which are stale, and exactly why. Every flagged claim carries a file:line reference as proof.

This skill is the standalone version of the audit that kb-init runs as part of its full flow. Run this any time you want to re-check documentation freshness without re-populating the vault.

Step 0: Preflight - Obsidian available and running?

Follow the Preflight Check in the obsidian-kb awareness skill (${CLAUDE_PLUGIN_ROOT}/skills/obsidian-kb/SKILL.md).

Step 1: Resolve the Project Vault

Follow the Vault Resolution Algorithm in ${CLAUDE_PLUGIN_ROOT}/skills/obsidian-kb/SKILL.md. Strict priority: user argument → path overlap → frontmatter → strong name match → STOP and ask.

Capture both $VAULT_NAME and $VAULT_PATH.

Print the confirmation line on your first reply:

"Using vault <Vault Name> at <path> (matched via <tier>). Auditing project docs against current code."

Step 1b: Vault Access Sequence

Switch Obsidian's active vault to the resolved one so post-audit CLI verification works:

CURRENT=$(timeout 3 obsidian vault info=name 2>/dev/null)
if [[ "$CURRENT" != "$VAULT_NAME" ]]; then
  ENCODED=$(printf '%s' "$VAULT_NAME" | sed 's/ /%20/g')
  open "obsidian://open?vault=${ENCODED}"   # macOS; xdg-open on Linux; start on Windows
  sleep 3
  CURRENT=$(timeout 3 obsidian vault info=name 2>/dev/null)
fi
if [[ "$CURRENT" == "$VAULT_NAME" ]]; then CLI_MODE=1; else CLI_MODE=0; fi

Step 2: Inventory Project Markdown Docs

Find every markdown file in the project (not the vault - the project's docs we're auditing):

find "$PWD" -type f \( -name '*.md' -o -name '*.mdx' \) \
  -not -path '*/node_modules/*' \
  -not -path '*/.git/*' \
  -not -path '*/dist/*' \
  -not -path '*/build/*' \
  -not -path '*/.next/*' \
  -not -path '*/target/*' \
  -not -path '*/vendor/*' \
  -not -path '*/venv/*' \
  -not -path '*/.venv/*' \
  -not -path '*/__pycache__/*' \
  2>/dev/null | sort