git:20260813.14437ae to git:20260813.c53db38

---

name: skill-doctor

disable-model-invocation: true

effort: low

description: "Environment diagnostics — check providers, auth, config, hooks, scheduler, and more"

trigger: |

EXPLICITLY USE when user asks about:

- "doctor" or "run doctor" or "diagnostics"

- "check my setup" or "is everything working"

- "health check" or "environment check"

- "what's wrong with my setup" or "why isn't octopus working"

- "check providers" or "check auth" or "check hooks"

DO NOT activate for:

- Initial setup (use /octo:setup)

- Project status or workflow progress (use /octo:status)

- Debugging application code (use /octo:debug)

---

# Environment Doctor

## Overview

Run environment diagnostics across 14 check categories. Identifies misconfigured providers, stale plugin installations, stale state, broken hooks, and other issues that prevent Claude Octopus from working correctly.

**Core principle:** Detect problems before they surface in workflows.

---

## When to Use

**Use this skill when:**

- Something isn't working and you're not sure why

- After installing or updating the plugin

- Before a demo or important workflow run

- Checking if providers are properly authenticated

- Verifying scheduler, hooks, or skills are correctly configured

**Do NOT use for:**

- First-time setup (use `/octo:setup` — it guides configuration)

- Project workflow status (use `/octo:status`)

- Debugging application code (use `/octo:debug`)

---

## The Process

### Step 1: Resolve Plugin Root and Run Full Diagnostics

Use this resolver before running Octopus scripts. Do not assume

`~/.claude-octopus/plugin` exists; Windows Git Bash installs may not support the

stable symlink. Run this as a single Bash call.

```bash

OCTO_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"

if [[ -z "$OCTO_PLUGIN_ROOT" || ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then

OCTO_PLUGIN_ROOT="${HOME}/.claude-octopus/plugin"

fi

if [[ ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]] && command -v octopus >/dev/null 2>&1; then

OCTO_BIN="$(command -v octopus)"

OCTO_PLUGIN_ROOT="$(cd "$(dirname "$OCTO_BIN")/.." && pwd)"

fi

if [[ ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then

OCTO_PLUGIN_ROOT="$(

find "${HOME}/.claude/plugins" -type f -path "*/scripts/orchestrate.sh" -print 2>/dev/null \

| sed 's#/scripts/orchestrate.sh$##' \

| { grep -E '(nyldn-plugins|claude-octopus|/octo(/[0-9]|$))' || true; } \

| sort \

| tail -1

)"

fi

if [[ -z "$OCTO_PLUGIN_ROOT" || ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then

echo "Claude Octopus plugin root not found. Reinstall the octo plugin, then retry doctor diagnostics."

exit 1

fi

mkdir -p "${HOME}/.claude-octopus"

_octo_stable="${HOME}/.claude-octopus/plugin"

if [[ ! -L "$_octo_stable" ]] || [[ "$(cd "$OCTO_PLUGIN_ROOT" 2>/dev/null && pwd -P)" != "$(cd "$_octo_stable" 2>/dev/null && pwd -P)" ]]; then

[[ -L "$_octo_stable" || -f "$_octo_stable" ]] && rm -f "$_octo_stable" 2>/dev/null || true

ln -s "$OCTO_PLUGIN_ROOT" "$_octo_stable" 2>/dev/null || true

fi

unset _octo_stable

export OCTO_PLUGIN_ROOT

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --verbose

```

This runs all 14 check categories and displays a formatted report.

### Step 2: Filter by Category (Optional)

If the user asks about a specific area, reuse the resolver from Step 1 and

replace its final `doctor --verbose` invocation with one of these lines. These

are replacement lines, not standalone shell calls; `OCTO_PLUGIN_ROOT` must be

resolved in the same Bash call.

```bash

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor providers

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor companions

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor auth

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor config

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor updates

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor state

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor smoke

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor hooks

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor scheduler

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor skills

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor conflicts

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor agents

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor recurrence

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor cache

```

### Step 3: Check & Install Dependencies

Reuse the Step 1 resolver and replace its final invocation with the dependency

checker to find missing CLIs, statusline config, and recommended plugins:

```bash

bash "$OCTO_PLUGIN_ROOT/scripts/install-deps.sh" check

```

If the check reports missing deps, offer to install them:

```bash

bash "$OCTO_PLUGIN_ROOT/scripts/install-deps.sh" install

```

This auto-installs Codex CLI, jq, and the statusline resolver. Antigravity CLI (`agy`) setup is detected and reported with install guidance. For plugins (claude-mem, document-skills), it prints `/plugin install` commands the user must run manually.

### Step 4: Verbose or JSON Output

As above, run these as the final line of the Step 1 resolver call:

```bash

# Detailed output for troubleshooting

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --verbose

# Machine-readable output

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --json

# Combine: specific category + verbose

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor auth --verbose

```

### Step 5: Interactive Remediation (MANDATORY for fixable issues)

After running diagnostics, if ANY fixable issues are found, you MUST use AskUserQuestion to offer fixes. Do NOT just print instructions — offer to execute them.

**RTK not installed:**

```javascript

AskUserQuestion({

questions: [{

question: "RTK saves 60-90% on bash output tokens. Install it now?",

header: "Install RTK",

multiSelect: false,

options: [

{label: "Install via brew (Recommended)", description: "brew install rtk — fast, macOS"},

{label: "Install via cargo", description: "cargo install rtk-token-killer"},

{label: "Skip", description: "Continue without RTK"}

]

}]

})

```

If user chooses install, run it, then offer hook setup.

**RTK installed but hook not configured on macOS/Linux:**

On Windows Git Bash, do not offer `rtk init -g`. RTK uses CLAUDE.md injection

mode there, so report the hook check as skipped.

```javascript

AskUserQuestion({

questions: [{

question: "RTK is installed but the Claude Code hook isn't active. Configure it?",

header: "RTK Hook",

multiSelect: false,

options: [

{label: "Run rtk init -g (Recommended)", description: "Auto-installs Claude Code bash hook on macOS/Linux"},

{label: "Skip", description: "I'll configure it later"}

]

}]

})

```

**Missing optional providers:**

```javascript

AskUserQuestion({

questions: [{

question: "Some providers are missing. Install them?",

header: "Providers",

multiSelect: true,

options: [

{label: "Codex CLI", description: "npm install -g @openai/codex"},

{label: "Antigravity CLI", description: "Install agy, then verify with agy --version && agy models"},

{label: "Skip all", description: "Continue with available providers"}

]

}]

})

```

**Auth expired:**

Offer to run the login command for the expired provider.

**Multiple fixable issues:** Batch them into a single AskUserQuestion with multiSelect where appropriate, rather than asking one at a time.

---

## Check Categories

| Category | What it checks |

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

| `providers` | Claude Code version, Codex CLI installed, Antigravity CLI installed, Perplexity API key, Ollama local LLM (server + models), circuit breaker status, provider fallback history |

| `companions` | Optional companion tools and integrations |

| `auth` | Authentication status for each provider |

| `config` | Plugin version, install scope, feature flags |

| `updates` | Loaded, installed, catalog, and cache versions; Claude marketplace auto-update; reload requirement |

| `state` | Project state.json, stale results, workspace writable |

| `smoke` | Smoke test cache, model configuration |

| `hooks` | hooks.json validity, hook scripts |

| `scheduler` | Scheduler daemon, jobs, budget gates, kill switches |

| `skills` | Skill files loaded and valid |

| `conflicts` | Conflicting plugins detection |

| `agents` | Agent definitions, worktree isolation, CLI registration, version compatibility |

| `recurrence` | Failure pattern detection — flags repeated quality gate failures, source hotspots, 48h trends |

| `cache` | Cache size, freshness, and hygiene |

Software dependency installation is checked separately by

`scripts/install-deps.sh check` in Step 3, including Node.js, jq, provider CLIs,

RTK token compression, the statusline resolver, and recommended plugins.

---

## Interpreting Results

### Healthy Output

All checks pass — no action needed.

### Common Issues and Fixes

| Issue | Fix |

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

| Codex CLI not found | `npm install -g @openai/codex` or install via `codex login` |

| Antigravity CLI not found | Install `agy`, then verify with `agy --version` and `agy models` |

| Perplexity not configured | `export PERPLEXITY_API_KEY="pplx-..."` (optional) |

| Circuit breaker OPEN | Provider had 3+ consecutive transient failures — wait for cooldown or check provider status |

| Stale state | Delete `.octo/state.json` and re-initialize |

| Invalid hooks.json | Check `hooks.json` syntax — must be valid JSON |

| RTK not installed | Offer to install: `brew install rtk && rtk init -g` (saves 60-90% tokens). Use AskUserQuestion to offer brew vs cargo install. |

| RTK installed but hook not configured | On macOS/Linux, offer `rtk init -g`; on Windows Git Bash, report skipped because RTK uses CLAUDE.md injection mode |

| RTK gain stats unavailable | Run some bash commands first, then check `rtk gain` to see token savings |

| Conflicting plugins | Uninstall conflicting plugins or adjust scope |

---

## Integration with Other Skills

| Scenario | Route |

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

| Doctor finds missing provider | Suggest `/octo:setup` to configure |

| Doctor finds stale project state | Suggest `/octo:status` to review |

| Doctor finds hook errors | Guide user to fix hooks.json |

| All checks pass, user still has issues | Suggest `/octo:debug` for deeper investigation |

---

## Hook Profile

Claude Octopus hooks can run in different profiles to balance cost and coverage.

Current profile: `$OCTO_HOOK_PROFILE` (default: standard)

Available profiles:

- **minimal** — Only session lifecycle and cost tracking hooks (lowest overhead)

- **standard** — All hooks except expensive review/security gates (default)

- **strict** — All hooks enabled including quality and security gates

Override: Set `OCTO_PROFILE=budget|balanced|quality` or `OCTO_DISABLED_HOOKS=hook1,hook2` to fine-tune. Legacy `OCTO_HOOK_PROFILE` still works (minimal→budget, standard→balanced, strict→quality).

---

## Intensity Profile

The doctor reports the active intensity profile — a single knob controlling hook gating, model selection, phase skipping, and context verbosity.

### What the Doctor Checks

- **Current profile**: `OCTO_PROFILE` value (budget/balanced/quality, default: balanced)

- **Profile source**: env var, legacy `OCTO_HOOK_PROFILE`, or auto-selected from intent

- **Hook gating**: which hooks are enabled/disabled at this profile level

- **Model hints**: which model (sonnet/opus) is recommended for each phase

- **Context verbosity**: compressed/standard/full

### Profile Summary

| Dimension | budget | balanced | quality |

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

| Hooks | essential only | standard (no quality gates) | all hooks |

| Models | Sonnet everywhere | Sonnet + Opus for synthesis | Opus for most phases |

| Phases | Skip discover if context given | Skip re-discovery | All phases run |

| Context | Compressed | Standard | Full inlining |

---

## Project Tier Hint

Also report `OCTO_TIER` when set. This is a recommendation hint, not a hard policy.

| Tier | Doctor guidance |

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

| `prototype` | Prefer faster checks and warn before high-cost provider fanout |

| `mvp` | Use balanced defaults and consensus on risky changes |

| `production` | Recommend full verification, security review, and stricter release gates |

If unset, show `OCTO_TIER=unset` and suggest setting it only when the project has a stable risk profile.

---

## Remote Session Checks

If `CLAUDE_CODE_REMOTE=true` or `OCTOPUS_REMOTE_SESSION=true`, report:

- remote session detected

- autonomous mode default active when no explicit autonomy is set

- provider probes skipped to conserve time/quota

- full HUD disabled unless `OCTOPUS_REMOTE_STATUSLINE=full`

- provider CLIs may need to be installed in the cloud setup script

Suggest `/octo:setup` only for configuration guidance; do not recommend interactive provider logins inside the remote session.

---

## Runtime Context

The doctor checks for project-level `RUNTIME.md` — a file that provides project-specific context (API endpoints, env vars, test commands, build steps) to orchestration prompts.

### What the Doctor Checks

- **RUNTIME.md exists** in the project root (also checks `.octopus/RUNTIME.md` and `.claude-octopus/RUNTIME.md`)

- If missing, suggest creating one from the template: `cp "${HOME}/.claude-octopus/plugin/config/templates/RUNTIME.md" ./RUNTIME.md`

- If present, confirm it contains at least one populated section (not just the template defaults)

### Why It Matters

Without a `RUNTIME.md`, orchestration prompts lack project-specific details — leading to generic advice about test commands, environment variables, and build steps. A populated `RUNTIME.md` makes every workflow more accurate.

---

## Quick Reference

`/octo:doctor` was removed in v9.41.0 to preserve Claude Code's native `/doctor` command.

Invoke this skill by asking Claude naturally, or run the orchestrator directly:

| What to say / run | Action |

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

| "run Octopus doctor diagnostics" | Run all 14 categories |

| "check Octopus providers" | Check provider installation only |

| `bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor auth --verbose` | Detailed auth status |

| `bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --json` | Machine-readable output |

Resolve and export `OCTO_PLUGIN_ROOT` with the Step 1 resolver before using either

direct command.