Diagnose

/diagnose

{SKILL_DIR} = this skill's own folder (locally: the directory this SKILL.md lives in; a served brain substitutes the real absolute path before you read this). Shared starter files live at the repo root two levels up: {SKILL_DIR}/../... If a path does not resolve, name the missing file and stop — never guess another location.

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: {SKILL_DIR}/../../scripts/diagnose.sh (the starter repo root sits two levels above this skill's folder on every install shape).

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

   Mac / Linux:

   bash "{SKILL_DIR}/../../scripts/diagnose.sh"
   # or pass an explicit vault:
   bash "{SKILL_DIR}/../../scripts/diagnose.sh" "/path/to/vault"
   

   Windows:

   pwsh "{SKILL_DIR}/../../scripts/diagnose.ps1"
   # or:
   pwsh "{SKILL_DIR}/../../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	A missing daily-journal is usually a STALLED INSTALL, not a missing skill. That skill is built in Phase 10a, so its absence means setup stopped before Phase 10 and every later phase never ran. Do not tell them to install one skill — that leaves the rest of the install missing. Point them at docs/RESUME_INSTALL.md and offer to resume. Only treat it as a genuinely missing skill if the vault also shows Phase 18+ artifacts (⚙️ Meta/journal-index.json), which would mean the install DID get past 10
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 the starter root ({SKILL_DIR}/../..)
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 "I never got the interview" / "setup said it was done but nothing happened" / "my CLAUDE.md is empty" / "nunca llegué a la entrevista" (a STALLED INSTALL — setup stopped partway and reported success. Do not diagnose it as N separate missing pieces; send them to docs/RESUME_INSTALL.md and resume from where the vault says they stopped)
• 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" / "<source> 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.