cortex-doctor

name	cortex-doctor
description	Health check + drift detection for the cortex-x install on this machine. Runs the bin/cortex-doctor.cjs CLI, parses findings, and offers interactive auto-fix for each non-ok check (Y/n per finding). Useful weekly, after a fresh install, after a migration to a new machine, or when cortex behavior feels off. Triggers (EN+CZ) "/cortex-doctor", "/doctor", "doctor", "healthcheck cortex", "co je rozbité na cortexu", "is cortex healthy", "cortex není v pořádku", "cortex broken". Surfaces hooks-registered status, CLAUDE.md discipline block status, source clone state, data home subdirs, skills + agents discovery. Composes with cortex-hooks-register and cortex-claude-md-augment for one-tap remediation.
disable-model-invocation	false

/cortex-doctor — health check + drift detection

You are running the cortex-x healthcheck. Goal: report install state in plain language, offer to fix anything that's broken, NEVER make destructive changes without consent.

Voice charter: see standards/voice.md. No greetings, no emoji, no emotion words. Counts not praise.

Step 1 — language signal

Read prior-turn language. If Czech, answer in Czech. Otherwise English.

Step 2 — run the CLI

Invoke the CLI via Bash tool:

cortex-doctor --json

If the cortex-doctor shim isn't on PATH (fresh install where PATH wasn't updated), fall back to:

node ~/.claude/shared/bin/cortex-doctor.cjs --json

Or in absolute Windows form:

node "$HOME/.claude/shared/bin/cortex-doctor.cjs" --json

Parse the JSON. The schema is:

{
  "ok": true | false,
  "counts": { "ok": N, "info": N, "warn": N, "error": N },
  "findings": [{ "id": "<check-id>", "severity": "ok|info|warn|error", "message": "<text>", "fix": "<command>|null" }],
  "cortex_data_home": "<path>",
  "cortex_source": "<path>"
}

Step 3 — present a compact report

Group findings by severity. ALWAYS surface error + warn first, ok last. Use a table or list — never prose paragraphs. Example output structure (Czech):

cortex-doctor:
  ✗ ERRORS (1)
    • <id>: <message>
      Fix: <command>
  ! WARNINGS (2)
    • <id>: <message>
      Fix: <command>
  ✓ OK (6)  [collapsed list of ids]

  Co je v pořádku · 6 čeků · 0 chyb · 2 varování.

Voice charter compliance: counts, not emotion. "1 chyba, 2 varování" not "ouvej, máš problémy".

Step 4 — offer auto-fix per non-ok finding

For EACH finding with severity ∈ {error, warn} AND non-null fix field, ask the operator if they want to run the fix command now. Use AskUserQuestion with two options per fix:

• Fix now — execute the fix command via Bash tool. Show output. Re-run cortex-doctor afterward to confirm the finding is gone.
• Skip — note + move to next finding.

Order findings by severity descending (errors first). Process one at a time so the operator can see each fix's effect before continuing.

For the most common fixes — DO NOT fabricate commands; use the exact fix field from the JSON. Examples:

• cortex-hooks-register — registers cortex hooks in ~/.claude/settings.json with backup.
• cortex-claude-md-augment — appends discipline block to ~/.claude/CLAUDE.md with backup.
• bash ~/cortex-x/install.sh (or pwsh ~/cortex-x/install.ps1) — re-runs installer.
• mkdir -p <path> — creates missing data home subdirs.

Safety rule: never run a fix command that wasn't surfaced by cortex-doctor's JSON output. The CLI is the SSOT for what's broken AND how to fix it.

Step 5 — final summary

After all fixes attempted, re-run cortex-doctor --json once more and print the final counts:

After fixes: 8 ok · 0 warn · 0 error.
cortex-x is healthy.

If errors remain after the fix attempts, point the operator at:

• ~/.claude/shared/INSTALL_NOTES.md for manual setup details
• https://github.com/Rejnyx/cortex-x/issues to file a bug if the fix didn't help

When NOT to use

• Mid-workflow (during /start, /audit, /designer flow) — that's not a doctor moment, it's a feature-flow moment. Resume the original task.
• Right after install.sh succeeded with the in-installer prompts (hooks + CLAUDE.md were just configured) — wait at least one Claude session before running doctor so SessionStart context can demonstrate they work.

Composes with

• cortex-hooks-register — most common error fix
• cortex-claude-md-augment — second most common info finding
• cortex-update --check — separate command for upgrade availability (cortex-doctor only verifies CURRENT install)