diagnose

/diagnose

Tells you whether your second brain is healthy.

Why

Most "Claude is broken" reports trace to one of:

• CLAUDE.md missing or has no Vault Map
• Hooks not registered, so no auto context-loading
• journal-index.json stale or malformed, so insights find nothing
• .ps1 files lost their UTF-8 BOM, so Windows PowerShell crashes
• ai-brain-starter is many commits behind, so the user is on stale logic

/diagnose checks all of these in ~5 seconds. It writes nothing, sends no network requests beyond a single git fetch, and exits with a status code so it can be wired into CI or cron.

What to do

1. Find the script. On the maintainer machine: ~/Desktop/ai-brain-starter/scripts/diagnose.sh. On an end-user install: ~/.claude/skills/ai-brain-starter/scripts/diagnose.sh.

2. Run it. Pick the right one for the platform:

   Mac / Linux:

   bash ~/.claude/skills/ai-brain-starter/scripts/diagnose.sh
   # or pass an explicit vault:
   bash ~/.claude/skills/ai-brain-starter/scripts/diagnose.sh "/path/to/vault"
   

   Windows:

   pwsh ~/.claude/skills/ai-brain-starter/scripts/diagnose.ps1
   # or:
   pwsh ~/.claude/skills/ai-brain-starter/scripts/diagnose.ps1 -Vault "C:\path\to\vault"
   

   By default it uses $VAULT_PATH if set, else the current directory.

3. Read the output to the user in plain language. Don't dump the raw report unless they ask. Translate:

   • All green: "Your vault is healthy. Nothing to do."
   • Only WARNs: "Working, but $N things to clean up. Want me to fix them?" Then offer to fix the specific WARNs (re-build journal index, add Vault Map to CLAUDE.md, pull latest ai-brain-starter, etc).
   • At least one FAIL: "Something is broken: [name the FAIL in one sentence]. I can fix it: [propose the fix]." Wait for confirmation, then fix.

What each check means

#	Check	If FAIL	If WARN
1	CLAUDE.md present + has Vault Map	Re-run /setup-brain Phase 4	Add the Vault Map section by hand
2	⚙️ Meta/ + scripts/ + rules/ present	Re-run /setup-brain Phase 3	Create the missing subfolder
3	ai-brain-starter + daily-journal skills installed	Re-run bootstrap	Install the missing skill from its phase
4	Hooks registered + graph-context-hook parses	Phase 5 wires hooks; bash -n the script	-
5	journal-index.json valid + fresh	Delete and rebuild via build-journal-index.py	Re-run /weekly to refresh
6	git, python3 (jq optional) on PATH	brew install / winget install	Optional tools missing
7	Vault is a git repo	-	Recommend git init for snapshot history
8	All .ps1 have BOM, no em dashes, parse clean	Fix the parser error	Add BOM and strip em dashes (see SKILL.md notes)
9	MCP config valid JSON	Fix the JSON	No MCPs registered (fine if intentional)
10	ai-brain-starter up to date with origin/main	Re-clone	git pull in ~/.claude/skills/ai-brain-starter
10b	No scheduled-task name collides with a skill; cron-only tasks _-prefixed	-	Rename per docs/MAINTENANCE.md
11	Vault on a local disk, not a consumer cloud-sync root	Move it local (docs/CLOUD_SYNC.md)	Could not evaluate the path
12	Vault has an off-machine backup	Set one up: bash scripts/vault-backup.sh setup (docs/BACKUP.md)	Backup configured but no snapshot yet
13	No repeated Obsidian renderer crashes (macOS; skips elsewhere)	-	Heavy indexer likely OOM-ing the renderer on a large vault: restricted mode -> Dataview only -> add others one at a time (see the obsidian-plugins rule, "Large-vault plugin posture")
14b	Ingest connectors still producing data (the silent-empty 0-vs-0 gap)	-	A connector exited 0 but returned 0 items (a vendor changed a surface): check its auth/permissions, re-run its ingest skill, confirm it pulls >0 items
17	No git worktree living inside the Obsidian-watched vault tree	-	The Desktop per-session worktree checkbox dropped a checkout under .claude/worktrees/ inside the vault -> renderer OOM/crash. Relocation is dead; the flag does NOT gate it. Relaunch the vault PLAIN with the worktree box UNCHECKED (cd <vault> && claude). See docs/VAULT_WORKTREE_MELT.md

When to suggest /diagnose proactively

• User says "Claude isn't reading my CLAUDE.md anymore"
• User says "the journal entries aren't showing up in /weekly"
• User says "I just did a git pull and something feels off"
• User says "my friend installed it but it's broken"
• User says "Obsidian keeps crashing when I open it" / "Obsidian won't open" (likely a heavy-indexer renderer OOM on a large vault - check 13)
• User says "my brain feels stale" / "I haven't seen any new Granola/WhatsApp/Slack/Gmail notes in a while" / " stopped showing up" (likely a silently-empty connector - check 14b)
• User says "Obsidian melted / pegged the CPU after I opened a Claude Desktop session" / "the vault doubled itself" / "there's a .claude/worktrees folder full of copies of my vault" (likely a worktree-on-vault checkout - check 17; relaunch PLAIN with the worktree box unchecked)
• After every major upgrade prompt during /setup-brain

Do NOT use /diagnose as an email-capture surface. If ~/.claude/.ai-brain-starter-email-on-file is missing, that is fine and never a finding — the email is optional, and the only places it is ever asked are the setup interview (Phase 24.4) and the once-per-update post-pull nudge. Never tell the user to fetch or paste a token.

Don't

• Don't run any of the FAIL fixes without confirming first.
• Don't pipe /diagnose output into a gh issue or anywhere public — it includes home directory paths.
• Don't treat a WARN about ai-brain-starter being behind as urgent. Default cadence is fine.