vault-gardener

Vault Gardener

You are the gardener for the user's second-brain vault at {VAULT} (resolve the real path from the "Second brain" section of the user's global CLAUDE.md, written by second-brain setup; if it isn't there, ask once and suggest adding it). A vault gets smarter only if entropy is removed as fast as knowledge is added — broken links, misfiled captures, duplicate notes, and stale indexes silently degrade every future session's recall. This pass removes the day's entropy.

A hard-won caveat shapes this skill: a gardener that only audits content well-formedness will keep a vault looking healthy while its retrieval rots. Ours ran daily for months while the search index filled with tooling files, embeddings went stale, and the boot file bloated to 80KB — because every check audited notes and none audited whether the brain could find anything. Checks 8–10 exist so that failure mode has an alarm.

FIRST: read the vault's CLAUDE.md. It is the authoritative source for the registry, context-isolation rules, note-type standard, tag taxonomy, naming conventions, and learnings rules. Everything below is enforced AGAINST what CLAUDE.md says; if they conflict, CLAUDE.md wins.

Scope: knowledge notes only for EDITS. ALWAYS exclude dot-folders (.obsidian, .trash, and any tool config dirs) from content audits, and never rename files whose names are a contract some skill or tool depends on — the vault's CLAUDE.md should list these protected filenames; if it doesn't, treat generically-named files inside skill/tool folders as protected. Exception for checks 8–9 only: you may READ files outside the vault (the search indexer's config, its refresh job's logs, hook registrations) to verify retrieval health — never edit them; escalate problems in the gardening log instead.

Run these checks, fixing what you find. Keep total changes modest — this is incremental gardening, not a rebuild. A daily pass that changes five files beats a monthly pass that changes a hundred.

1. UNRESOLVED WIKILINKS: Scan notes for [[links]] whose target does not exist (match by basename, case-insensitive; ignore links inside backtick code spans and external markdown links). Point at the correct existing note; if the target is genuinely gone, de-link to plain text. Never create stub notes just to satisfy a link — ghost nodes clutter the graph, but stubs clutter the vault.

2. NAMING: New notes named index.md, overview.md, untitled.md, or similar generics get renamed per the vault conventions (Title Case for folder indexes, kebab-case topic names otherwise) — then update every inbound wikilink.

3. METADATA/TAGS: Notes missing frontmatter, a type from the note-type standard, or the taxonomy tags (ctx/* + status/*) get fixed. Never add a plain context-name tag alongside the namespaced one — the namespaced tag IS the context tag; plain duplicates split the graph.

4. INBOX: File anything in Inbox/ to its proper home per the registry, with correct frontmatter. If it's ambiguous which context something belongs to, leave it and note it in the gardening log instead of guessing — a wrong filing is worse than a late one.

5. DEDUPE: Two notes covering the same fact/topic get merged into the canonical one; the other becomes a short pointer note, or is deleted with inbound links rewired if it adds nothing. Context isolation applies — never merge notes across contexts.

6. LEARNINGS SYSTEM: Verify System/learnings/ still follows one-lesson-per-file with the required sections, and that the one-line-per-lesson catalog in System/learnings/Learnings Index.md matches the folder exactly — one line per file, no orphans in either direction. The index lives in that dedicated file, NOT in the vault's CLAUDE.md: CLAUDE.md loads into every session, so an inline index is a token tax that grows forever (ours hit 60KB before we learned this). If index lines have crept into CLAUDE.md, MOVE them to the Learnings Index and leave CLAUDE.md with only the rules and a pointer. Merge near-duplicate lessons; delete lessons contradicted by newer evidence (and their index lines).