lint

name	lint
description	Run health checks on the vault wiki — find contradictions, orphan pages, stale claims, missing backlinks, suggest new concept pages. Triggers on: '/lint', 'health check', 'check vault', 'find issues', 'wiki lint'. Inspired by Karpathy's LLM knowledge base lint operation.

Lint Skill

Health checks for the vault wiki. Find problems, suggest improvements, keep the knowledge base self-healing.

When to Run

• On /lint
• As part of weekly /reflect
• After bulk captures (5+ items in one session)

Pipeline

Read vault/index.md → Scan all vault folders → Run checks → Report → Offer fixes → Update index

---

Step 1: Load the Index

Read vault/index.md — every page should be listed here. This is the reference for most checks.

Step 2: Run Health Checks

2a. Orphan pages (not in index)

Scan all vault/ subdirectories for .md files (excluding folder READMEs and system files). Compare against index entries. Flag: any vault file NOT listed. Fix: add to index with a proper summary.

2b. Dead index entries

Every index entry → does the file still exist? Flag: entries pointing to deleted files. Fix: remove from index.

2c. Missing backlinks

For each page with [[wikilinks]], check whether the linked page links back. Flag: one-way links where bidirectional linking adds value. Fix: add reciprocal links.

2d. Unlinked pages

Compile-on-write requires every knowledge file to have ≥1 hub link (its stream) + ≥1 outbound link. Flag: pages with an empty or missing ## Related section. Fix: propose links.

2e. Stale claims

Files > 14 days old with status: New or action_required: true; MEMORY.md facts with [verified:] > 90 days old. Flag and suggest: update status, re-verify, or archive.

2f. Duplicate detection

Very similar titles or summaries across folders. Flag potential duplicates. Suggest: merge or differentiate. Always manual review.

2g. Missing stream IDs

Files without stream_id in frontmatter that clearly belong to a stream (per the config block's stream list). Fix: propose the stream_id, show preview, then apply.

2h. Broken mirror links (OPTIONAL — only if a cloud mirror is enabled)

Files with mirror_page_id: PENDING or empty. Suggest: sync now or mark as vault-only. Skip this check entirely if integrations.cloud_mirror: none.

2i. Concept gaps

Topics mentioned 3+ times across different files with no dedicated page. Suggest: create a concept page in vault/research/ (draft it, confirm before writing).

2j. Vault scale check

Count knowledge .md files (excluding system files and READMEs):

• < 400 pages: index-first + grep is optimal. No action.
• 400–499: warn — "Approaching scale limit; see MEMORY.md Scale Triggers."
• ≥ 500: report prominently — time to evaluate local vector/hybrid search; grep-based retrieval may degrade. (Evidence: structured semantic search only pays for its complexity at this scale.)

2k. Correction recurrence

Read vault/notes/accuracy-log.md. Group corrections by original → corrected type pair. Flag: any pattern with 3+ occurrences. Suggest: a classification-rule addition to the capture skill (show diff, confirm).

2l. Log integrity

vault/log.md should have a session-end or operation line for recent sessions. Flag: sessions or heartbeat runs that left no log line (audit gap).

---

Step 3: Report

Vault Lint Report — YYYY-MM-DD

Stats: 42 pages | 5 streams | 6 system files

CRITICAL (fix now):
- 3 orphan pages not in index
- 2 dead index entries

WARNINGS:
- 4 files missing stream_id
- 2 potential duplicates
- 3 items stuck at status:New for 14+ days

SUGGESTIONS:
- "caching strategy" mentioned in 4 files — create concept page?
- Missing backlink: referral-idea → growth-review
- Stream content-creation: 12d silent (threshold 7d)

Index completeness: 39/42 pages (93%)

Step 4: Offer Fixes

Fix options:
1. [Auto] Add 3 orphan pages to index — confirm?
2. [Auto] Remove 2 dead index entries — confirm?
3. [Preview] Add stream_id to 4 files — show preview?
4. [Manual] Review 2 potential duplicates
5. [Auto] Add missing backlinks (3 pairs) — confirm?

Autonomy rules:

• Index updates and backlink additions: auto-fix with confirmation
• stream_id additions: show preview, then fix
• Duplicates and status changes: always manual
• Concept pages: draft and confirm

Step 5: Update Index + Log

After fixes, refresh vault/index.md (update the _Last updated:_ line and page count) and append to vault/log.md:

## [YYYY-MM-DD HH:MM] lint | 42 pages, 5 critical fixed, 3 suggestions open

---

Rules

• Never delete vault files during lint — only flag
• Never modify file content without confirmation — only add metadata
• Index updates are safe to auto-apply (additive)
• When run inside /reflect, keep the report to the top 5 issues