| name | vault-doctor |
| description | Diagnostic and repair skill for the Obsidian vault. Runs a battery of checks against vault notes and offers to fix detected issues. Dry-run by default — requires 'fix' to write. Use when: (1) /vault-doctor command to scan for vault health issues, (2) /vault-doctor fix to apply repairs, (3) /vault-doctor --check <name> for a specific check, (4) user reports stale backlinks or wants to audit vault integrity. |
| metadata | {"version":"1.2.0"} |
vault-doctor — Audit and Repair the Obsidian Vault
Audit and repair the Obsidian vault. Ships with one check initially (source-sessions); more can be added as separate modules under scripts/vault_doctor_checks/ without changing this skill.
Tools needed: Bash, Read
Invocation
/vault-doctor — run all checks, report only (dry-run)/vault-doctor fix — run all checks, apply after per-project confirmation/vault-doctor --check source-sessions — run one specific check/vault-doctor --check snapshot-integrity — snapshot orphans, broken backlinks, stale/missing session snapshot lists, status/summary mismatches/vault-doctor --check snapshot-migration — migrate pre-spec snapshots (legacy filenames, missing status/backlink fields, missing session snapshot lists). Runs 4 ordered sub-checks; idempotent./vault-doctor --days 14 — override default window (default: 7 days)/vault-doctor --project obsidian-brain — limit to one project/vault-doctor fix --check source-sessions --days 7 — combine flags
Procedure
Follow these steps exactly. Do not skip steps or reorder them.
Step 1 — Parse arguments and locate the dispatcher
Parse the user's invocation into flags:
- No args → dry-run mode, all checks
fix → apply mode, all checks--check <name> → specific check only--days <N> → window override--project <name> → project filter
Locate the Python dispatcher via the standard plugin cache glob, with a fallback for local dev sessions where the repo is checked out as $PWD:
DISPATCHER="$(ls -dt ~/.claude/plugins/cache/*/obsidian-brain/*/scripts/vault_doctor.py 2>/dev/null | head -1)"
if [[ -z "$DISPATCHER" ]]; then
if [[ -f "$(pwd)/scripts/vault_doctor.py" ]]; then
DISPATCHER="$(pwd)/scripts/vault_doctor.py"
fi
fi
if [[ -z "$DISPATCHER" || ! -f "$DISPATCHER" ]]; then
echo "ERROR: could not find scripts/vault_doctor.py" >&2
exit 1
fi
If the dispatcher cannot be located, tell the user:
Could not find scripts/vault_doctor.py. Make sure the obsidian-brain plugin is installed via /dev-test install (for local dev) or the marketplace.
Stop here if the dispatcher is missing.
Step 2 — Run the dispatcher in JSON report mode
Always run with --json first so you can parse the output deterministically. Pass through only the flags the user provided:
ARGS=()
[[ -n "${CHECK:-}" ]] && ARGS+=(--check "$CHECK")
[[ -n "${DAYS:-}" ]] && ARGS+=(--days "$DAYS")
[[ -n "${PROJECT:-}" ]] && ARGS+=(--project "$PROJECT")
ARGS+=(--json)
python3 "$DISPATCHER" "${ARGS[@]}"
Capture stdout as the JSON report. Exit codes:
0 — clean vault, nothing to do1 — issues found (expected for a dry-run that finds things)2 — apply errors3 — usage error (bad args, missing config)
If exit code is 3, surface the stderr message directly to the user and stop.
Step 3 — Present the report to the user
Parse the JSON and present a grouped-by-project table.
For each issue, after the proposed: line (when present), render a
signal: <capture_signal> (conf <capture_confidence>) line. The values
come from the top-level capture_signal and capture_confidence fields
in the JSON payload (not from extra.*). capture_confidence reports
how reliable the capture-time signal is (created_at=1.0, date=0.9,
filename=0.85, mtime=0.5); the issue's top-level confidence field
reports the rewrite-proposal confidence per the strict 3-band taxonomy:
0.99 = uuid-basename-stale (auto-applyable basename-only repair);
0.5 = date-window-hint (operator must content-grep before applying);
0.0 = unresolved / uuid-day-mismatch / missing-session-note (never auto-apply).
The two fields are distinct — render capture_confidence here so
heuristic-fall cases are visible (e.g., signal=mtime conf=0.5 indicates
no immutable signal was available — the operator should sample a few flagged
notes before running fix). For unresolved issues with no proposed: line,
render signal: after reason:.
Render signal_class (from the top-level signal_class field) as a prefix tag so operators
can distinguish: [uuid-basename-stale], [uuid-day-mismatch],
[missing-session-note], [date-window-hint], [unresolved]. The
convergence_warning/convergence_count fields are deprecated as of #106
(UUID-first matching obsoleted the convergence guard) — they remain in the
JSON payload as hard-coded defaults for output schema stability but should
not drive rendering.
Example:
vault_doctor report — 3 issue(s) across 1 check(s)
## source-sessions
### Project: obsidian-brain (2 issues)
[FAIL] 2026-04-10-recall-profiling.md
current: [[2026-04-09-obsidian-brain-abcd]]
proposed: [[2026-04-10-obsidian-brain-ef01]]
signal: date (conf 0.9)
reason: note calendar day 2026-04-10 (signal=date, conf=0.9) overlaps session ef010000 window most, not current source abcd0000
### Project: tiny-vacation-agent (1 issue)
[FAIL] 2026-04-11-enrichment-scope.md
current: [[2026-04-10-tiny-vacation-agent-aaaa]]
proposed: [[2026-04-11-tiny-vacation-agent-bbbb]]
signal: created_at (conf 1.0)
reason: note capture_time 2026-04-11T09:15:00+00:00 (signal=created_at, conf=1.0) matches session bbbb0000 window, not current source aaaa0000
Use [FAIL] for actionable issues (those with a proposed fix) and [WARN] for unresolved ones (those the check could not auto-repair). Always include a one-line summary at the top with the total count.
If the report is empty (exit code 0), tell the user:
Vault is clean. No issues found.
Stop here.
Step 4 — Ask whether to apply (only if fix was requested)
If the user did NOT pass fix:
Dry-run complete. Found N stale backlink(s) across K project(s).
Run /vault-doctor fix to apply repairs. Backups will be written to ~/.claude/obsidian-brain-doctor-backup/<timestamp>/.
Stop here.
If the user DID pass fix:
Found N repairable issue(s) across K project(s). I'll apply per project with confirmation.
Re-run the dispatcher with --apply (do NOT pass --yes — let the dispatcher prompt per project interactively):
ARGS=()
[[ -n "${CHECK:-}" ]] && ARGS+=(--check "$CHECK")
[[ -n "${DAYS:-}" ]] && ARGS+=(--days "$DAYS")
[[ -n "${PROJECT:-}" ]] && ARGS+=(--project "$PROJECT")
ARGS+=(--apply)
python3 "$DISPATCHER" "${ARGS[@]}"
The dispatcher will prompt Apply N fix(es) for project 'X' in check 'Y'? [y/N] on stderr for each project. Relay each prompt to the user and pipe their response to the dispatcher's stdin.
Step 5 — Report the outcome
Parse the final stderr output from the dispatcher and summarize:
vault_doctor apply complete
obsidian-brain: 3 applied, 0 unresolved, 0 errors
tiny-vacation-agent: 1 applied, 0 unresolved, 0 errors
Backups saved to: ~/.claude/obsidian-brain-doctor-backup/2026-04-11T17-04-22+00-00/
If any errors occurred (exit code 2), surface them prominently and recommend the user diff one of the backup files under the backup root to understand what went wrong.
Step 6 — Offer next steps
After a successful fix run:
Repairs applied. You can diff any fixed note against its backup under the backup root.
Re-run /vault-doctor to confirm the vault is clean.
Notes for the model
- All detection and repair logic lives in
scripts/vault_doctor.py and scripts/vault_doctor_checks/*.py. Do not re-implement any of it in this skill. The skill is pure orchestration and presentation.
- The dispatcher is dry-run by default. Pass
--apply only when the user explicitly requests fix.
- Unresolved issues are never automatically repaired. Surface them in the report but do not try to guess a replacement.
- Backups are written automatically by the dispatcher to
~/.claude/obsidian-brain-doctor-backup/<ISO-timestamp>/<project>/<basename>. Always mention the backup path in your summary so the user knows where to look.
