Diagnose

---
type: skill
name: diagnose
description: 'Use when an AI Brain vault needs a health check or something feels off: Claude ignores CLAUDE.md, journal entries missing from /weekly, hooks not firing, something broke after a git pull, a friend''s install misbehaves, Obsidian crashes or pegs the CPU, a .claude/worktrees folder appeared, Granola/WhatsApp/Slack/Gmail notes stopped arriving, or Windows .ps1 scripts error. Also after major /setup-brain upgrades. Not for debugging code; audits the vault install only.'
trigger: /diagnose
argument-hint: "[vault path, defaults to $VAULT_PATH or current directory]"
tool_access:
  - Bash
  - Read
  - Glob
  - Grep
policy_constraints:
  - rule: Never modify vault files; this is a read-only self-check
    exception_handling: Surface the issue to the user with a remediation hint, do not auto-fix
  - rule: Never write findings outside the user's terminal report
    exception_handling: Print to stdout only; no log files or vault writes
  - rule: Treat missing CLAUDE.md, missing Meta folder, or stale journal index as red findings, not silent skips
    exception_handling: Emit a red status row naming the missing artifact
required_inputs:
  - name: vault_path
    type: path
    required: false
    description: Path to the vault root. Defaults to $VAULT_PATH env var or current working directory.
output_shape:
  format: terminal-report
  fields:
    status_rows: list of {check_name, color (green/yellow/red), detail}
    summary_line: one-line overall health status
    exit_code: 0 if all green, 1 if any yellow, 2 if any red
---

# /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
   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.

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.