adelaidasofia /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.jsonstale or malformed, so insights find nothing.ps1files 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
Find the script:
{SKILL_DIR}/../../scripts/diagnose.sh(the starter repo root sits two levels above this skill's folder on every install shape).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_PATHif set, else the current directory.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.mdand 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" / " 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/worktreesfolder 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
/diagnoseoutput into agh issueor anywhere public — it includes home directory paths. - Don't treat a WARN about ai-brain-starter being behind as urgent. Default cadence is fine.