/obsidian-health

description: Run a vault health check - grouped by severity, detects contradictions, concept gaps, stale claims, and structural issues
category: meta
triggers_en: ["vault health", "check vault", "audit vault", "vault diagnostics"]
triggers_de: ["Vault-Gesundheit", "Vault prüfen", "Vault auditieren", "Vault-Diagnose"]
triggers_es: ["salud del vault", "revisa el vault", "audita el vault", "diagnóstico del vault"]
triggers_pt: ["saúde do vault", "verifique o vault", "audite o vault", "diagnóstico do vault"]
triggers_zh: ["检查知识库健康状况", "给我的知识库做体检", "审计我的笔记库", "诊断知识库问题"]

Use the obsidian-second-brain skill. Execute `/obsidian-health`:

1. Read `_CLAUDE.md` first to find the vault path 2. Run the health scan from the skill root (its absolute path was given at session start as **Skill root**; substitute it for `SKILL_ROOT`): `uv run --directory "SKILL_ROOT" scripts/vault_health.py --path ~/path/to/vault --json` (replace vault path with the one from `_CLAUDE.md`)

• **Large or noisy vault?** If the scan surfaces thousands of findings from directories the user does not maintain by hand (atomic-card pools, backup snapshots, imported dumps), do NOT hardcode fixes. Offer to write a `<vault>/.vault-config.json` that extends the exclude list: `{"exclude-dirs": ["_card-pool"], "exclude-paths": ["Archive/Backup"]}`. `exclude-dirs` matches directory names anywhere in the tree; `exclude-paths` matches vault-relative path prefixes. Both are additive - the built-in excludes always apply - and a missing or malformed file is ignored silently. Re-run the scan afterward.
• **`source_payload` findings?** (#194) Three different problems under one type. An `error` naming one source means the note declares `capture_scope: full-local` or `bounded-local` and has essentially no body - it claims evidence it does not hold, so re-capture it or set `capture_scope: url-only` and say so plainly. A `warning` naming a source plus the notes that link it means active knowledge rests on a `url-only` record: the vault kept the locator, not the evidence. Offer to re-capture the source, or to mark the dependent claims as URL-backed; never resolve it by copying a complete copyrighted work. The single `info` line counting sources with no `capture_scope` is every source written before the field existed - fill them in as you touch them, do not sweep the vault. `"source_policy": "strict-local"` in `.vault-config.json` raises the last two by one severity.
• **`source_quality` findings?** (#258) A `warning` names a concept, synthesis or other note that cites only sources graded `speculation`: provenance unknown, derived or conflicting. It is not a claim that the note is wrong. Offer to corroborate its claims with a better source (the bounded lateral read in `references/source-quality-check.md`, only on an explicit yes), or to say in the note that they are unverified. A source with no `source_quality` is unjudged and never reported. `"source_quality_policy": "silent"` in `.vault-config.json` mutes the check.
• **`source_quality_unlabelled` findings?** (#258) A `warning` names a `type: source` note whose first lines say it is unverified, unconfirmed or speculative while its frontmatter has no `source_quality`. The prose is right, the field is missing. Offer to add `source_quality: speculation`, or a higher grade if the note shows the provenance capture saw. The same policy key mutes it.
• **`rewrite_policy: unattended` info line?** The vault has opted out of the confirm-before-rewrite gate in `/obsidian-ingest` (#250) and reviews rewrites through its own layer. Nothing to fix; the line is there so a reader of the report knows the vault runs without the gate. Remove the key from `.vault-config.json` to restore the default.

3. Parse the JSON output and split findings into categories 4. Spawn parallel subagents to handle each category simultaneously:

• **Wanted-notes agent**: the script reports `wanted_note` items - links to a note that does not exist yet. These are NOT errors: in a wiki-style vault you link a thing the moment you mention it, so wanted notes are a demand-ranked wishlist of pages worth writing, not breakage. Triage them with `uv run --directory "SKILL_ROOT" scripts/triage_links.py --path <vault> --limit N`, which sorts each into keep (a deliberate seed, leave it), create (referenced enough to deserve a real note now), or delete (junk or a typo - fix the link). Report-only by default; needs `ANTHROPIC_API_KEY`. Headless on purpose: it can run unattended or on a schedule. The goal is to triage the backlog, never to drive the count to zero.
• **Duplicates agent**: confirm duplicates are truly the same concept, not just similar names
• **Taxonomy agent**: only fires when `<vault>/_meta/taxonomy.md` exists (format in `references/taxonomy-format.md`) - the script's `tag_synonym` and `tag_not_in_taxonomy` findings are empty otherwise, so a vault without the file sees nothing. `tag_synonym` means a note's tag is a known synonym of a canonical tag: the fix is unambiguous, so offer to rewrite that note's `tags:` frontmatter to the canonical form, per note, with explicit confirmation before editing - never batch-rewrite across the vault unattended. `tag_not_in_taxonomy` means the tag matches neither a canonical tag nor a synonym: report it as informational only - it may be a legitimate new tag - and never auto-fix it; the taxonomy file is a human-curated vocabulary, not something this command edits on its own.
• **Frontmatter agent**: identify notes missing required fields by type. If the script reports a `code_fence_wrapped` note (frontmatter trapped inside a leading ```` ```markdown ```` fence), the fix is to **unwrap it** - strip the opening fence line and the matching closing ```` ``` ```` so the inner `---` frontmatter and body become real markdown. **Never add a new frontmatter block to a wrapped note** - that produces duplicate frontmatter and leaves the body trapped. If the note already has bot