mycelium-hq/ai-brain-starter/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).

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

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

Windows: ``powershell 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.

1. 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

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.