Skip to main content

​
/doctor Command

Run a comprehensive diagnostic on your pro-workflow and Claude Code setup. Identifies configuration issues, context problems, and setup gaps.

​
Syntax

/doctor
No arguments required.

​
What It Checks

1

Pro-Workflow Installation

Verifies commands and database are installed:
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"
Status: OK | NEEDS SETUP
2

Hooks Status

Checks if hooks.json is loaded and hooks are active:
cat ~/.claude/settings.local.json 2>/dev/null | head -5
Checks:
  • hooks.json in correct location
  • Script paths use ${CLAUDE_PLUGIN_ROOT} or absolute paths
  • Scripts have execute permissions
Status: ACTIVE | INACTIVE
3

Context Health

Measures context window usage:
/context
Thresholds:
  • Usage < 70%: Healthy
  • Usage 70-90%: Warning — Consider /compact
  • Usage > 90%: Critical — Compact immediately or start fresh
Status: Healthy | Warning | Critical
4

MCP Servers

Counts active MCP servers and tools:Target: <10 servers, <80 toolsStatus: OK | TOO MANY
5

CLAUDE.md Size

Checks memory file length:
wc -l CLAUDE.md 2>/dev/null || echo "No CLAUDE.md found"
Thresholds:
  • < 60 lines: Ideal
  • 60-150 lines: Acceptable
  • > 150 lines: Too long — Split into modules
Status: Ideal | Acceptable | Split Recommended
6

Git Status

Checks for uncommitted changes and stale stashes:
git status --short
git stash list
Flags:
  • Uncommitted changes → Commit or stash
  • Stale stashes → Clean up
Status: Clean | X uncommitted files
7

Settings Validation

Checks for conflicting settings:
cat .claude/settings.json 2>/dev/null | head -3
cat ~/.claude/settings.json 2>/dev/null | head -3
Checks:
  • Conflicting settings between project and user level
  • Permission rules are correct
Status: OK | Conflicts Detected

​
Quick Fixes

The /doctor command provides fixes for common issues:
IssueFix
Commands missingcp -r /path/to/pro-workflow/commands/* ~/.claude/commands/
Database missingmkdir -p ~/.pro-workflow && npm run build (in plugin dir)
Hooks not firingCheck paths in hooks.json use absolute paths
Context degradedRun /compact or start fresh session
Too many MCPsDisable unused: disabledMcpServers in settings
CLAUDE.md too longSplit into root + package-level files

​
Example Output

> /doctor

Pro-Workflow Health Check
=========================

✓ Installation:  OK
  Commands: ~/.claude/commands/ (11 found)
  Database: ~/.pro-workflow/data.db (47 learnings)

✓ Hooks:         ACTIVE
  18 hook events registered
  Last hook: PostToolUse (2 minutes ago)

⚠ Context:       78% (warning)
  Recommendation: Run /compact at next task boundary

⚠ MCPs:          12 active (too many)
  Tools: 94 total
  Recommendation: Disable unused MCPs
  Rarely used: context7 (0 uses this session)

✓ CLAUDE.md:     58 lines (ideal)
  Location: ./CLAUDE.md

✓ Git:           clean
  No uncommitted changes
  No stale stashes

✓ Settings:      OK
  No conflicts detected

Overall: 2 warnings, 0 errors

​
When to Run /doctor

Scheduled health check:
  • Every Monday or at start of sprint
  • After installing new MCPs
  • After major config changes
  • When sessions feel slow

​
Interpreting Results

​
Installation Issues

Commands Missing: 
# Claude Code plugin install
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow

# Or manual install
cp -r /path/to/pro-workflow/commands/* ~/.claude/commands/
Database Missing: 
cd ~/.claude/plugins/*/pro-workflow
npm install && npm run build

​
Hook Issues

Hooks Inactive: Check hooks.json paths: 
{
  "hooks": {
    "PostToolUse": {
      "Edit": {
        "script": "${CLAUDE_PLUGIN_ROOT}/scripts/post-edit.js"
      }
    }
  }
}
Ensure scripts are executable: 
chmod +x scripts/*.js

​
Context Issues

High Context Usage (>70%): 
# Check current usage
/context

# Compact at task boundary
/compact

# Or start fresh session
# (after /wrap-up to save state)
Critical Context Usage (>90%): Start a fresh session immediately. High context degrades quality.

​
MCP Issues

Too Many MCPs (>10 servers): Disable unused MCPs in settings.json: 
{
  "disabledMcpServers": ["context7", "memory"]
}
Or remove from mcp.json: 
# Check usage
/mcp stats

# Remove unused
rm ~/.claude/mcp/servers/unused-server.json

​
CLAUDE.md Issues

File Too Long (>150 lines): Split into modular files: 
project/
├── CLAUDE.md                  # Root (project-wide patterns)
├── packages/
│   ├── api/
│   │   └── CLAUDE.md         # API-specific patterns
│   └── frontend/
│       └── CLAUDE.md         # Frontend-specific patterns
See Split Memory Guide for details.

​
Best Practices

Run Weekly

Schedule a weekly /doctor check to catch config drift early.

After Plugin Updates

Run /doctor after updating pro-workflow or Claude Code.

Before Big Features

Verify health before starting large features with /develop.

Share Reports

Share /doctor output when asking for support or reporting issues.

​
Troubleshooting

If /doctor isn’t recognized:
  1. Check plugin installation: 
    ls ~/.claude/commands/doctor.md
  2. Try with full namespace: 
    /pro-workflow:doctor
  3. Reinstall plugin: 
    /plugin install pro-workflow@pro-workflow
If database isn’t found:
  1. Check location: 
    ls ~/.pro-workflow/data.db
  2. Initialize database: 
    cd ~/.claude/plugins/*/pro-workflow
npm run db:init
  3. Verify SQLite support: 
    node -e "require('better-sqlite3')"
If hooks aren’t firing:
  1. Check hooks.json location: 
    ls .claude/hooks/hooks.json
ls ~/.claude/hooks/hooks.json
  2. Verify script paths: 
    cat .claude/hooks/hooks.json | grep script
  3. Test hook manually: 
    node .claude/hooks/scripts/post-edit.js

/wrap-up

Full session audit after fixing issues

Settings Guide

Complete settings reference

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us