git:20260620.d5e44bb to git:20260707.f0ac903

1 added, 1 removed. Audit A to A.

---

type: skill

name: diagnose

- description: Run a self-check against an installed AI Brain Starter vault. Verifies CLAUDE.md, Meta folder, skills, hooks, journal index, MCPs, .ps1 BOM/em-dash hazards, and ai-brain-starter freshness. Prints a green/yellow/red report. Run any time something feels off, or after a git pull, or when onboarding someone else's vault.

+ 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

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

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:**

```powershell

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

|---|---|---|---|

| 4 | Hooks registered + graph-context-hook parses | Phase 5 wires hooks; bash -n the script | - |

| 7 | Vault is a git repo | - | Recommend `git init` for snapshot history |

| 10b | No scheduled-task name collides with a skill; cron-only tasks `_`-prefixed | - | Rename per docs/MAINTENANCE.md |

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