Vault Gardener

---
name: vault-gardener
description: Recurring maintenance pass for a second-brain vault — link hygiene, naming, metadata/tags, Inbox filing, dedupe, learnings-index sync, index-note freshness, plus retrieval-health metrics, context-economy byte budgets, and a daily recall canary. Run daily as a scheduled agent (or weekly by hand). Keeps recall precise as the vault grows; without gardening, a knowledge vault decays into a junk drawer with a search bar. Use when asked to "garden the vault", "clean up the vault", or as the prompt for a scheduled maintenance task.
---

# 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).

7. **INDEX FRESHNESS:** Pick 1-2 project index notes (rotate day by day) and check their stated facts against the notes and session logs in their folder — stale statuses, dead links, missing new work. Update what's wrong. This is the check that keeps the registry believable.

8. **RETRIEVAL HEALTH** (read-only outside the vault; skip sub-checks that don't apply to this vault's tooling — but say so in the log rather than silently). The point of a vault is that it can be SEARCHED; a well-formed note nobody can find is still a failure:
   a. If the vault has a semantic-search indexer (qmd or similar): check its status for a stale/pending-embedding backlog. Small backlog → refresh it yourself and note it. Recurring backlog → the scheduled refresh job is broken; read its log and escalate what you find.
   b. Sanity-check index scope: compare the indexer's document count for the vault against the actual knowledge-note count on disk (same include/exclude rules the indexer is configured with). A gap over ~5% either way means the indexer's include pattern has drifted — typically a new top-level folder nobody added, or tooling files leaking in. Do NOT edit the indexer's config; name the drift in the log as an escalation.
   c. If recall automation exists (e.g. a prompt hook that auto-searches the vault): verify the script exists, is executable, and is still registered. Escalate breakage.

9. **CONTEXT ECONOMY** (byte budgets on always-loaded files — anything read into every session's context, so growth here is a tax on every prompt): the vault's CLAUDE.md should stay under ~25KB / ~200 lines; apply the same bar to any other file the user's setup loads at session start. If over budget, move the overflowing content OUT to a referenced note (the way the learnings index lives in its own file) and leave a pointer — never silently delete rules. If the restructure is more than mechanical, propose it in the log as an escalation instead of doing it. Report current sizes in every log so the trend is visible.

10. **RECALL CANARY** (end-to-end test of the failure this skill exists to prevent): pick ONE concrete, distinctive fact from a session log written in the last 7 days (a name, number, or decision — not a generic phrase). Search for it the way a future session would — the vault's keyword search first (note: many FTS engines AND every term, so query with 2–4 distinctive keywords, not a sentence), then semantic search if available. If the source log is not in the top handful of results either way, write a **RECALL FAILURE** line in the log with the exact fact, the queries tried, and the expected file — this is the alarm the entire retrieval stack exists to ring. Record the canary result (pass/fail + query) in every log.

11. **STATE NOTES** (only if the vault uses rolling `{Project} State.md` current-facts notes): flag in the log any State note that is an empty shell, or untouched for 21+ days while new session logs accumulated in that project — that means write-backs are skipping it. Do NOT populate State notes yourself from guesswork; they must be filled by sessions that actually worked the project.

**WRITE-BACK (required):** Write a gardening log to `Session-Logs/general/YYYY-MM-DD-HH_MM-vault-gardening.md` (create the `general` folder on first run; frontmatter per vault conventions) summarizing: checks run, files changed (paths), the retrieval-health numbers (indexer backlog, doc count vs disk count, boot-file sizes, canary pass/fail), anything skipped as ambiguous, escalations, and open items for the next run. If nothing needed fixing, still record the health numbers — they are the trend line, and the log's existence is how you know the loop is alive.

**FINALLY:** If many files changed (roughly 10+), refresh whatever search index the vault uses — including its embedding/vector step if it has one, not just the keyword index (a keyword-only refresh is how embedding backlogs silently accumulate). Ignore failures if no indexer is configured.

Constraints: never touch files outside the vault except the read-only checks in 8; never delete a note you did not just verify is redundant or empty; prefer updating existing notes over creating new ones; keep the vault's conventions exactly as its CLAUDE.md specifies.

## Scheduling

This prompt is designed to run unattended. Options, best first:
- **Claude Code scheduled task / cron** — daily, off-hours (we run 07:08). Incremental daily beats big-batch weekly: smaller diffs, fresher indexes, mistakes caught within a day.
- **Manual cadence** — invoke the skill weekly; expect bigger diffs and budget accordingly.

One more scheduling rule, learned the hard way: **when the vault's structure changes (an index moves, a folder renames), update this gardener's prompt the same day.** A scheduled task faithfully enforcing yesterday's structure will revert your migration at its next run.