Add /cairn-doctor health-check command

[SnowboardTechie]

Problem / Motivation

cairn-notes has multiple moving parts: identity at ~/.claude/cairn/identity.md, Obsidian vaults under ~/notes/, .notes/ symlinks per repo, optional MCPs (Exa, Context7), registered skills and agents. When one quietly breaks — missing identity, broken symlink, vault moved, MCP not running — the failure mode is usually a confused subagent giving worse-than-baseline output rather than an explicit error.

The only existing diagnostic surface is /cairn-setup, which is geared at first-run bootstrap, not ongoing health verification. There is no equivalent of oh-my-openagent's doctor for "is everything wired up correctly right now?"

Proposed behavior

A /cairn-doctor slash command that runs a non-mutating health check across the plugin's runtime dependencies and reports a one-screen summary with status per check, plus a one-line next-step when a check fails.

Scope

In scope

• Identity: ~/.claude/cairn/identity.md exists, parses, required fields present
• Vaults: configured vault paths resolve and are writable; ~/notes/second-brain/ exists when expected
• .notes/ resolution: trunk-resolution lands somewhere sensible from cwd, including from a worktree
• Skills: each plugin skill's SKILL.md readable, has frontmatter
• Agents: each agent file readable
• Optional MCPs (Exa, Context7): report present / absent, not pass/fail (they're optional, not required)
• Read-only — never repairs, only reports

Out of scope

• Auto-repair (separate command if wanted later)
• Network probes against MCP servers beyond "is it registered"
• Vault-content validation (Obsidian / scribe concern, not health)

Implementation hints

• Likely lives in plugins/cairn-notes/commands/cairn-doctor.md alongside cairn-setup.md
• Reuse trunk-resolution from agent-workspace so the worktree case is exercised
• Output terse: one line per check, status glyph, one-line next-step on failure
• Should detect the failure mode in archivist: vault search fails from a worktree (trunk-resolution missing) #59 (archivist vault search broken from a worktree)

Acceptance criteria

• /cairn-doctor runs to completion without mutating any file
• Every check above surfaces pass / fail / optional status
• When a check fails, output names the next step (file path, command, etc.)
• Runs cleanly from both trunk and a worktree

Open questions

• Slash command, skill, or both? Slash command feels right for a one-shot diagnostic; a skill might be more discoverable.
• Should this auto-run at the end of /cairn-setup once identity is written?

Related

• Companion issues filed alongside: autonomous "run until done" loop skill; interview-mode planner skill
• Adjacent: archivist: vault search fails from a worktree (trunk-resolution missing) #59 (archivist vault search fails from a worktree) — doctor should detect this

[SnowboardTechie]

Reframing update — see #86.

Still in scope, renamed to /cairn-doctor.

Health-check command is genuinely useful for catching the silent-failure modes you described (missing identity, broken symlinks, MCP not running).

/athena-doctor → /cairn-doctor aligns with the cairn-notes rename, and "cairn-doctor" reads cleanly — you're checking whether the trail markers are still trustworthy.

Path note for the implementer: post-Phase 0.5, the diagnostic targets are ~/.claude/cairn/identity.md and the cairn-notes plugin directory.

Tagged reframing-2026.