vault-lint

Vault Lint — Knowledge Base Health Check

Inspired by Karpathy's "Lint" philosophy: periodically scan the vault to surface inconsistencies, broken links, orphan pages, and data gaps.

Workflow

Step 1: Environment Detection

1a. Detect vault root — follow ../../_shared/common-steps.md "Vault Detection" section.

1b. Scan all article files:

Glob("**/*.md", path="$VAULT_ROOT")

Exclude .claude/, .git/, .playwright-mcp/, reviews/, node_modules/ directories. Build the file list $ALL_ARTICLES.

Step 2: Six Checks

Check 1: Broken Links

Scan all articles for [[wikilink]] and [[wikilink|alias]]:

Grep("\\[\\[.*?\\]\\]", path="$VAULT_ROOT", glob="**/*.md", output_mode="content")

For each wikilink:

1. Extract the link target (the part before |)
2. Look for a matching file in $ALL_ARTICLES (filename without .md extension)
3. No match → record as broken link, note the source file and line number

Check 2: Orphan Pages

For each file in $ALL_ARTICLES:

1. Extract the filename (without path and extension)
2. Search all other articles for [[filename]] or [[filename|
3. No inbound links → record as orphan page

Exclude index.md, README.md, CLAUDE.md (these naturally have no inbound links).

Check 3: index.md Consistency

1. Read $VAULT_ROOT/index.md
2. Compare against $ALL_ARTICLES:
   • Entry in index.md but file doesn't exist → ghost entry
   • File exists but no entry in index.md → missing entry
3. Check whether total_articles count in the index.md header is accurate

Check 4: Cross-Reference Suggestions

For each article:

1. Extract 3-5 core keywords (from title and tags)
2. Search other articles for these keywords
3. If article A frequently mentions core concepts of article B but has no [[B]] link → suggest adding a cross-reference

This check is time-intensive; limit to 10 most recently modified articles per run.

Check 5: Summary Quality