Skip to content

benoror/obsidianos_work / .agents/skills/vault-health

vault-health

Verified

Audit the vault for structural issues: unresolved wikilinks, orphan notes, dead-end notes, and Obsidian sync conflicts. Optional --fix flags create stubs or surface fixable issues.

Vault Health

Usage

  • /vault-health — Run all checks, present a triage report.
  • /vault-health unresolved — Only show unresolved [[wikilinks]].
  • /vault-health orphans — Only show notes with no incoming links.
  • /vault-health deadends — Only show notes with no outgoing links.
  • /vault-health sync — Only check Obsidian sync conflicts.
  • /vault-health --fix-people — For unresolved [[@*]] links, prompt to create Teams/People/@Name.md stubs in batch (delegates to /people-stubs).

Why this skill exists

The vault grows over time and accumulates structural debt:

  • Dead [[@Jane Doe]] links because the person file was never created.
  • Notes orphaned in subfolders, never linked from any project/team page.
  • Sync conflicts when two devices edit the same file simultaneously.

This skill surfaces all of that in one pass.

Workflow

Preflight (O5): Run .scripts/check-obsidian-cli.sh. Abort if it fails.

Step 1: Run all checks (or the subset requested)

CheckCommandWhat it returns
Unresolved linksobsidian unresolved format=jsonAll [[link]] pointers with no target file.
Orphansobsidian orphans format=jsonFiles no other file links to.
Deadendsobsidian deadends format=jsonFiles with no outgoing links.
Sync conflictsobsidian sync:status format=jsonFiles with unresolved sync versions.

Run only the requested subset; full sweep when no argument is given.

Step 2: Categorize and present

Group findings by type and severity:

## Unresolved wikilinks (12)

People-flavored ([[@*]]) — likely missing People files:
| # | Link | Referenced in (count) |
|---|------|----------------------|
| 1 | [[@Jane Doe]] | 6 meetings |
| 2 | [[@John Smith]] | 3 meetings |

Other unresolved:
| # | Link | Referenced in |
|---|------|---------------|
| 3 | [[+SomeNewTeam]] | 1 meeting |

## Orphan notes (4)
| # | Path | Created | Reason it might matter |
|---|------|---------|------------------------|
| 1 | Meetings/Engineering/Old Notes.md | 2026-01-12 | Probably needs to link to a project page |

## Deadend notes (8)
...

## Sync conflicts (0)
✓ All synced.

For people-flavored unresolved links, sort by count descending — most-referenced unresolved person is most worth creating a file for.

Step 3: Offer fixes

  • For --fix-people (or after presenting): prompt the user to create People stubs in batch. Delegate to /people-stubs which handles the actual creation.
  • For orphans/deadends: don't auto-fix. They might be intentional. Just surface.
  • For sync conflicts: don't auto-fix. Sync conflicts need human judgment. Surface and tell the user to resolve via Obsidian's UI or obsidian sync:history.

Step 4: Commit

See /commit. The skill itself doesn't write files (except via /people-stubs if invoked). If anything changed, commit message: chore(vault-health): create N people stubs from unresolved links (or similar).

Sync conflict resolution

When obsidian sync:status reports conflicts:

  1. List them with obsidian sync:status format=json (path + version count per file).
  2. For each conflicted file, surface in the report with these next-action hints:
    • View versions: obsidian sync:history file="<path>" — see what each side wrote.
    • Read a specific version: obsidian sync:read file="<path>" version=<N> — preview without writing.
    • Restore: obsidian sync:restore file="<path>" version=<N> — pick one side.
    • Manual merge (preferred when both sides have meaningful changes): open the file in Obsidian, use the Sync history pane to pick chunks.
  3. Never auto-restore — sync conflicts mean both sides have edits the user might want. Surface and let them choose.

Display sync conflicts at the top of the report (not last) — they're time-sensitive (the longer they sit, the more divergent the versions get).

Important Notes

  • The skill is read-only by default — only --fix-people triggers writes (and even then, via /people-stubs with confirmation).
  • Some orphans are intentional (e.g. USER.md, README.md). Consider an exclusion list in a future iteration.
  • Sync conflict detection assumes Obsidian Sync is configured. If not, this check is a no-op (prints "✓ Sync not configured — skipped").
  • Obsidian CLI requires the desktop app to be running. If it's not, the skill should print a helpful error.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall