doctor

/learning-loop:doctor

A read-mostly diagnostic. Runs the health-check library, presents the result, and walks you through fixes one at a time.

If invoked with --redact, skip the normal health-check steps and run the Redact mode section instead.

Paths

Resolve PLUGIN_DATA, VAULT, and the plugin root per ${CLAUDE_PLUGIN_ROOT}/skills-shared/paths-preamble.md (read it and apply).

fix strings in the health-check JSON prefix paths with a user-facing PLUGIN shorthand for the plugin root (defined in guide/troubleshooting.md; the guide/ tree is not shipped with the plugin). Show them verbatim when the user will run the command; substitute ${CLAUDE_PLUGIN_ROOT} for the leading PLUGIN segment when you execute it yourself via Bash.

Step 1: Run all checks

node ${CLAUDE_PLUGIN_ROOT}/scripts/health-check.mjs --full --json

Parse the JSON. The schema:

{
  "ts": "...",
  "ran": "full",
  "checks": [
    { "id", "name", "status": "ok" | "fail", "severity": "ok" | "warn" | "fail", "detail", "fix" }
  ]
}

Step 2: Present the report

Format the dashboard like this:

learning-loop doctor
====================

Health checks (N passed, M warnings, F issues):

  ✓ Node.js                     v25.9.0
  ✓ Claude Code                 2.1.145
  ⚠ ~/.local/bin on PATH        not on PATH
    → Add to your shell rc: export PATH="$HOME/.local/bin:$PATH"
  ✗ ll-search binary            missing at /Users/.../bin/ll-search
    → Run /learning-loop:init to re-download the binary
  …

F issues, M warnings.

Icon rules:

• ✓ when status === "ok"
• ⚠ when status === "fail" && severity === "warn"
• ✗ when status === "fail" && severity === "fail"

Step 3: If F + M === 0

Print ✓ All checks pass. Nothing to fix. and exit.

Step 4: Otherwise, iterate fails first, then warns

For each check with status === "fail":

1. Show the check:

   ✗ <name>: <detail>
     Suggested fix: <fix>
   

2. Ask via AskUserQuestion:
   • Option A: Fix this (auto-runnable) — only when the fix is in the auto-runnable table below
   • Option A': Run the suggested command and tell me when done — when the fix is manual
   • Option B: Skip — I'll handle this later
   • Option C: Stop the doctor session — exits cleanly
3. On choice A: execute the corresponding fix command via Bash. After it finishes, re-run node ${CLAUDE_PLUGIN_ROOT}/scripts/health-check.mjs --full --json and find the same check by its id field. Report:
   • ✓ Fixed (new state: <detail>) if the check now returns ok
   • ⚠ Still warning: <new detail> if it improved to warn
   • ✗ Still failing: <new detail> if it didn't help (don't loop — move on)
4. On choice A' (manual): print the command, then ask Done? [Y]es / [N]o. On Yes, re-run node ${CLAUDE_PLUGIN_ROOT}/scripts/health-check.mjs --full --json and find the same check by its id field, then report as above.
5. On choice B: track as skipped and move to next.
6. On choice C: print summary and exit.