diagnose

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.
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 ~/.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:

   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

#	Check	If FAIL	If WARN
1