/doctor

description: Diagnose pro-workflow setup and Claude Code configuration

/doctor - Configuration Health Check

Run a diagnostic on your pro-workflow and Claude Code setup.

Check These

1. Pro-Workflow Installation

ls -la ~/.claude/commands/wrap-up.md 2>/dev/null && echo "Commands: OK" || echo "Commands: MISSING"
ls -la ~/.pro-workflow/data.db 2>/dev/null && echo "Database: OK" || echo "Database: MISSING"

2. Hooks Status

Check if hooks.json is loaded and hooks are active. Run:

cat ~/.claude/settings.local.json 2>/dev/null | head -5

If hooks aren't firing, check:

• hooks.json is in the right location
• Script paths use `${CLAUDE_PLUGIN_ROOT}` or absolute paths
• Scripts have execute permissions

2a. Deterministic Hook Sanity

Verify each hook script on both happy and failing inputs:

# commit-validate: valid passes, bad format blocks (exit 2)
echo '{"tool_input":{"command":"git commit -m \"feat: x\""}}' | node "$CLAUDE_PLUGIN_ROOT/scripts/commit-validate.js" && echo "commit-validate pass: OK"
echo '{"tool_input":{"command":"git commit -m \"not conventional\""}}' | node "$CLAUDE_PLUGIN_ROOT/scripts/commit-validate.js" 2>&1; test $? -eq 2 && echo "commit-validate block: OK"

# secret-scan: clean passes, hardcoded key blocks
echo '{"tool_input":{"content":"hello"}}' | node "$CLAUDE_PLUGIN_ROOT/scripts/secret-scan.js" && echo "secret-scan pass: OK"
echo '{"tool_input":{"content":"key=\"AKIAIOSFODNN7EXAMPLE\""}}' | node "$CLAUDE_PLUGIN_ROOT/scripts/secret-scan.js" 2>&1; test $? -eq 2 && echo "secret-scan block: OK"

# git-blast-radius: safe passes, destructive blocks
echo '{"tool_input":{"command":"git status"}}' | node "$CLAUDE_PLUGIN_ROOT/scripts/git-blast-radius.js" && echo "git-blast-radius pass: OK"
echo '{"tool_input":{"command":"git reset --hard"}}' | node "$CLAUDE_PLUGIN_ROOT/scripts/git-blast-radius.js" 2>&1; test $? -eq 2 && echo "git-blast-radius block: OK"

Every line should print an `OK`. Missing any means the script is silently broken.

2b. Git Safety Override

If you need to run a blocked git operation deliberately (e.g. intentional `git reset --hard` during recovery), export `PRO_WORKFLOW_ALLOW_UNSAFE_GIT=1` for the shell that will run it. Never set it globally.

3. Context Health

/context

• Usage < 70%: Healthy
• Usage 70-90%: Consider `/compact`
• Usage > 90%: Compact immediately or start fresh

4. MCP Servers

Check active MCPs. Target: <10 servers, <80 tools.

5. CLAUDE.md Size

wc -l CLAUDE.md 2>/dev/null || echo "No CLAUDE.md found"

• < 60 lines: Ideal
• 60-150 lines: Acceptable
• > 150 lines: Too long, split into modules

6. Git Status

git status --short
git stash list

• Uncommitted changes? Commit or stash.
• Stale stashes? Clean up.

7. Settings Validation

cat .claude/settings.json 2>/dev/null | head -3
cat ~/.claude/settings.json 2>/dev/null | head -3

• Check for conflicting settings between project and user level
• Verify permission rules are correct

8. Wiki Knowledge Base

node $PRO_WORKFLOW_ROOT/skills/wiki-builder/scripts/wiki-cli.js list 2>/dev/null
node $PRO_WORKFLOW_ROOT/skills/wiki-research-loop/scripts/research-loop.js status 2>/dev/null
ls -1 ~/.pro-workflow/STOP 2>/dev/null && echo "KILL SWITCH ACTIVE — no research runs"
tail -5 ~/.pro-workflow/tick.log 2>/dev/null

• List of wikis · seed counts per status · kill-switch state · last cron-tick activity
• Embeddings require an OpenAI or Voyage key configured for this plugin. BM25 search remains local and needs no key. Never print environment values or read credential files.

9. Council Providers

In a plugin session, call `run_provider_task` on the `providers` MCP server with `{"task":"council","args":["providers"]}`. It reports configured status without revealing values. The command below is for standalone CLI use.

node $PRO_WORKFLOW_ROOT/skills/llm-council/scripts/council.js providers 2>/dev/null

• Shows which pro-workflow credentials are configured (Anthropic/OpenAI/OpenRouter/Fireworks/custom), without exposing values.

Quick Fixes

| Issue | Fix | |-------|-----| | Commands missing | `cp -r /path/to/pro-workflow/commands/* ~/.claude/commands/` | | Database missing | `mkdir -p ~/.pro-workflow && npm run build` (in plugin dir) | | Hooks not firing | Check paths in hooks.json use absolute paths | | Context degraded | Run `/compact` or start fresh session | | Too many MCPs | Disable unused: `disabledMcpjsonServers` in settings | | CLAUDE.md too long | Split into root + package-level files |

Report

After running checks, summarize:

Pro-Workflow Health Check
  Installation:  OK / NEEDS SETUP
  Hooks:         ACTIVE / INACTIVE
  Context:       XX% (healthy/warning/critical)
  MCPs:          X active (OK / TOO MANY)
  CLAUDE.md:     XX lines (OK / SPLIT RECOMMENDED)
  Git:           clean / X uncommitted files