From obsidian-kb
Audits project markdown docs against code, flags stale claims with file:line evidence, categorizes as current/partially-stale/stale/aspirational, outputs single audit note to Obsidian vault.
npx claudepluginhub waelmas/codeplow --plugin obsidian-kbThis skill uses the workspace's default tool permissions.
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.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Executes ctx7 CLI to fetch up-to-date library documentation, manage AI coding skills (install/search/generate/remove/suggest), and configure Context7 MCP. Useful for current API refs, skill handling, or agent setup.
Generates production-ready Python code for Dataverse SDK with error handling, singleton clients, retry logic, OData optimizations, logging, and type hints.
Share bugs, ideas, or general feedback.
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.
Follow the Preflight Check in the obsidian-kb awareness skill (${CLAUDE_PLUGIN_ROOT}/skills/obsidian-kb/SKILL.md).
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."
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
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
If the result is empty - no project markdown to audit - tell the user and stop. This skill has nothing to do.
If a single user argument is passed (e.g., /kb-audit README.md), scope the audit to just that file or glob. Skip the full inventory.
If the inventory returned more than ~10 files, confirm with the user first - audit uses compute:
"I found N markdown docs in this project. I'll audit each one: quote-and-verify 2-3 concrete claims per doc against the current code, flag stale claims with file:line evidence, and write a Documentation Audit note to the vault. Takes 1-3 minutes. Proceed? [Y/n]"
If ≤10 docs, skip the confirmation - it's quick enough to just run.
Dispatch a single general-purpose subagent (not Explore - it needs to write the note via filesystem). Pass the doc inventory and $VAULT_PATH.
Subagent prompt template:
Status Reporting Protocol (required): End your response with exactly one of:
STATUS: DONE- audit complete, note written.STATUS: DONE_WITH_CONCERNS- completed with notes; concerns listed below.STATUS: NEEDS_CONTEXT- missing info; do NOT write the note.STATUS: BLOCKED- hit a blocker (denied tool, missing command). Describe concretely. Do NOT fabricate content.
Audit the existing markdown documentation in the project at
<pwd>. You're given this inventory:<doc inventory from Step 2>For each doc, determine:
- Purpose - what the doc claims to be about.
- Freshness signals - last modified date (
staton macOS;git log -1 --format=%cI <file>), last commit message, references to deprecated features.- Accuracy spot-check - pick 2-3 concrete claims in each doc and verify against the code:
- Command in README → confirm in package.json / Makefile / scripts.
- File path reference → confirm the file exists at that path.
- Version claim → confirm in lock files.
- Feature description → confirm the feature still exists in code.
- Version-numerically stale patterns - a common failure mode worth flagging separately. The doc is architecturally accurate but has frozen-in-time version metadata:
- README badges with outdated versions (e.g.,
![Next.js 13.0]whenpackage.jsonhas Next 15.x).- "Requires Node N+" claims vs. current
engines/.nvmrc.- "Currently in alpha/beta" when the project is on a mature version tag.
- Installation sections referencing old dep versions.
- Roadmap / Coming Soon items that actually shipped months ago.
- Overall verdict - current / partially stale / stale / aspirational (describes plans, not reality).
Write the audit to
$VAULT_PATH/Research/Documentation Audit.mdvia filesystem (NOT viaobsidian create- the CLI ignoresvault=and would write to the active vault only). Use this structure:--- type: reference created: <today's date> audit_date: <today's date> --- # Documentation Audit Audit of existing project markdown docs, checked against current code. Every claim flagged as stale includes a concrete file:line reference as evidence. ## Summary <N docs audited, M current, S partially stale, X stale, A aspirational> ## Docs by Status ### Current (accurate & up to date) - `<path>` - <purpose>. Last touched <date>. ### Partially stale - **`<path>`** - <purpose>. Issues: - Claim: "<quote>" - Evidence: `<file>:<line>` - <what's actually there> - Correction: <current truth> ### Stale - **`<path>`** - <purpose>. Likely out of date since <date> / version X. - Primary evidence: `<file>:<line>` - <concrete example> ### Aspirational - **`<path>`** - describes planned state rather than current reality. - Evidence: <what's missing vs described> ## Version-Numerically Stale <docs that are architecturally accurate but have frozen version metadata> ## Recommended Actions - **`<doc>`**: update section "<heading>" - says "<claim>", should say "<correction>" (see `<file>:<line>`) - **`<doc>`**: deprecate - functionality moved to `<new-location>` (git log `<commit>`) - **`<doc>`**: keep - historical value; flag at top with "Historical - may not reflect current architecture"Write with filesystem commands:
mkdir -p "$VAULT_PATH/Research" cat > "$VAULT_PATH/Research/Documentation Audit.md" <<'NOTE_EOF' ... content ... NOTE_EOFHard rule: do not flag any doc as stale without a concrete
file:lineor command-output reference proving the staleness. If you can't produce evidence, do not flag the claim. Speculation is useless - the audit's value is verifiable pointers the user can click.Keep it pragmatic - don't nitpick minor wording. Focus on claims that would mislead an agent or engineer trying to follow the docs today.
Same pattern as kb-init Step 4b (see ${CLAUDE_PLUGIN_ROOT}/skills/kb-init/SKILL.md):
If $VAULT_PATH/Index.md exists and doesn't already link the audit, append a link:
if [[ -f "$VAULT_PATH/Index.md" ]] && ! grep -q 'Documentation Audit' "$VAULT_PATH/Index.md"; then
printf '\n- [[Research/Documentation Audit]] - Freshness audit of project markdown\n' \
>> "$VAULT_PATH/Index.md"
fi
If the audit note already existed and was overwritten (a re-run), leave the Index as-is - the link was already there.
Show the user:
"Audited N docs. M are current, S partially stale, X stale. Written to
Research/Documentation Audit.mdin the vault.Top actions (if any):
- <1-3 highest-impact fixes, each with a file:line pointer>
Click through the Documentation Audit note for the full list with evidence."
Suggest /kb-audit when:
Don't suggest it:
/kb-init - that already ran the audit.obsidian CLI only for CLI-specific ops.obsidian commands with timeout (see the awareness skill's Rule 2).$VAULT_PATH/...) - not obsidian create vault=..., which is ignored.file:line evidence.