# /grid:doctor - Grid Diagnostic Tool --- name: grid:doctor description: Diagnose Grid health and suggest fixes allowed-tools: - Read - Glob - Grep - Bash disable-model-invocation: true argument-hint: "[--fix]" --- Run comprehensive health checks on The Grid installation and environment. Diagnoses issues and suggests (or automatically applies) fixes. ## USAGE `/grid:doctor` - Run diagnostics and report issues `/grid:doctor --fix` - Run diagnostics and attempt automatic repairs ## DIAGNOSTIC CHECKS ### 1. Environment Check Detect and validate the runtime environment: - [ ] Detect platform (macOS, Linux, WSL, Windows) - [ ] Check Node.js version and installation path - [ ] Verify npm installation - [ ] Check for WSL PATH issues (Windows only) - [ ] Verify Claude Code CLI is installed **Implementation:** ```bash # Platform detection uname -s # Darwin, Linux, etc. uname -r # Kernel version # Node.js which node node --version # npm which npm npm --version # Claude Code which claude claude --version 2>/dev/null || echo "Not found" ``` ### 2. Installation Check Verify Grid files are properly installed: - [ ] `~/.claude/commands/grid/` exists - [ ] `~/.claude/agents/` contains grid-*.md files (expect 17) - [ ] VERSION file exists and contains valid semver **Implementation:** ```bash # Commands directory ls -la ~/.claude/commands/grid/ # Agent count ls ~/.claude/agents/grid-*.md 2>/dev/null | wc -l # VERSION cat ~/.claude/commands/grid/VERSION ``` ### 3. Agent Health For each agent in `~/.claude/agents/grid-*.md`: - [ ] File exists and is readable - [ ] Has valid YAML frontmatter (starts with `---` block) - [ ] Has `name:` field in frontmatter - [ ] Has `model:` field (opus, sonnet, haiku, or inherit) - [ ] Has `permissionMode:` field (plan or acceptEdits) ### 4. State Health (if .grid/ exists) If an active Grid session exists: - [ ] STATE.md exists and is parseable - [ ] config.json is valid JSON (if exists) - [ ] budget.json is valid JSON (if exists) - [ ] No orphaned phase files (PLAN.md without corresponding directory structure) **Implementation:** ```bash # Check STATE.md cat .grid/STATE.md 2>/dev/null || echo "No active session" # Validate JSON files python3 -c "import json; json.load(open('.grid/config.json'))" 2>/dev/null && echo "config.json: valid" || echo "config.json: invalid or missing" python3 -c "import json; json.load(open('.grid/budget.json'))" 2>/dev/null && echo "budget.json: valid" || echo "budget.json: invalid or missing" ``` ### 5. Hook Health Verify hooks are properly configured: - [ ] `hooks/` directory exists - [ ] `enforce-delegation.sh` exists and is executable - [ ] `hooks.json` is valid JSON ### 6. Dependencies Check for required external tools: - [ ] ripgrep (rg) is installed - [ ] git is installed and configured - [ ] Python 3 is available (for JSON validation) **Implementation:** ```bash # ripgrep which rg && rg --version # git which git && git --version # Python 3 which python3 && python3 --version ``` ### 7. Configuration Health Validate settings: - [ ] Model tier is valid (quality, balanced, or budget) - [ ] Budget limit is non-negative number (if set) - [ ] No conflicting settings between config files ## OUTPUT FORMAT ``` GRID DOCTOR v{VERSION} ====================== Environment ----------- Platform: {Darwin/Linux/WSL/Windows} Node: {version} ({path}) npm: {version} Claude CLI: {version or "not found"} Installation ------------ Commands: ~/.claude/commands/grid/ [OK] Agents: {N}/17 found [OK/WARN/FAIL] VERSION: {version} [OK] Agents ------ Frontmatter: [OK/WARN] name field: {N}/17 [OK/WARN] model field: {N}/17 [OK/WARN] permissions: {N}/17 [OK/WARN] State ----- .grid/: [EXISTS/MISSING] STATE.md: [OK/EMPTY/MISSING] config.json: [OK/INVALID/MISSING] budget.json: [OK/INVALID/MISSING] Hooks ----- hooks/: [OK/MISSING] delegation: [OK/NOT EXECUTABLE/MISSING] hooks.json: [OK/INVALID/MISSING] Dependencies ------------ ripgrep: [OK] {version} git: [OK] {version} python3: [OK] {version} Configuration ------------- Model tier: {quality/balanced/budget} Budget limit: {$amount or "none"} --------------------------------- Overall: HEALTHY / NEEDS ATTENTION / UNHEALTHY {Suggestions section if issues found} End of Line. ``` ## STATUS INDICATORS Use these symbols for status: - `[OK]` - Pass (all good) - `[WARN]` - Warning (functional but suboptimal) - `[FAIL]` - Fail (broken, needs fix) - `[SKIP]` - Skipped (not applicable) ## EXPECTED AGENT FILES The Grid expects these 17 agent files in `~/.claude/agents/`: 1. grid-planner.md 2. grid-executor.md 3. grid-recognizer.md 4. grid-scout.md 5. grid-debugger.md 6. grid-researcher.md 7. grid-visual-inspector.md 8. grid-e2e-exerciser.md 9. grid-persona-simulator.md 10. grid-refinement-synth.md 11. grid-accountant.md 12. grid-git-operator.md 13. grid-guard.md 14. grid-memory.md 15. grid-coordinator.md 16. grid-critic.md 17. grid-updater.md ## FRONTMATTER VALIDATION Valid frontmatter example: ```yaml --- name: grid-executor description: Executes planned tasks with atomic commits model: inherit permissionMode: acceptEdits --- ``` Required fields: - `name:` - Must match filename (without .md) Recommended fields: - `description:` - Brief description of agent role - `model:` - One of: opus, sonnet, haiku, inherit - `permissionMode:` - One of: plan, acceptEdits ## AUTO-FIX CAPABILITIES (--fix flag) When `--fix` is provided, doctor will attempt: | Issue | Fix | |-------|-----| | Missing .grid/ directory | Create it | | Invalid config.json | Reset to defaults | | Non-executable hook script | `chmod +x` the script | | Missing VERSION file | Create with current version | | Malformed budget.json | Reset to `{}` | | Missing ripgrep | Suggest install command | Issues that CANNOT be auto-fixed: - Missing agent files (requires reinstall) - Invalid agent frontmatter (requires manual review) - Corrupted STATE.md (requires mission restart) - Missing Node.js or Claude CLI ## NO ISSUES FOUND If all checks pass: ``` GRID DOCTOR v1.7.x ================== Environment ----------- Platform: Darwin (macOS 14.x) Node: v20.x.x (/usr/local/bin/node) npm: 10.x.x Claude CLI: 1.x.x Installation ------------ Commands: ~/.claude/commands/grid/ [OK] Agents: 17/17 found [OK] VERSION: 1.7.x [OK] Agents ------ Frontmatter: [OK] name field: 17/17 [OK] model field: 17/17 [OK] permissions: 17/17 [OK] State ----- .grid/: [SKIP] No active session STATE.md: [SKIP] config.json: [SKIP] budget.json: [SKIP] Hooks ----- hooks/: [OK] delegation: [OK] hooks.json: [OK] Dependencies ------------ ripgrep: [OK] 14.x.x git: [OK] 2.x.x python3: [OK] 3.x.x Configuration ------------- Model tier: balanced Budget limit: none --------------------------------- Overall: HEALTHY The Grid is functioning within normal parameters. End of Line. ``` ## COMMON ISSUES AND FIXES ### Issue: "ripgrep not found" **Fix:** - macOS: `brew install ripgrep` - Linux: `apt install ripgrep` or `cargo install ripgrep` - Windows: `choco install ripgrep` ### Issue: "Agent files missing" **Fix:** ```bash # Reinstall The Grid npm install -g the-grid-cc # Or copy from source cp -r /path/to/grid/agents/* ~/.claude/agents/ ``` ### Issue: "Invalid config.json" **Fix with --fix flag:** ```bash /grid:doctor --fix # Resets to: {"modelTier": "balanced", "budgetLimit": null} ``` ### Issue: "hooks not executable" **Fix with --fix flag:** ```bash /grid:doctor --fix # Runs: chmod +x hooks/enforce-delegation.sh ``` ## CONTEXT USAGE WARNING If context usage exceeds 50%, doctor will add a warning: ``` Context Warning: {N}% context used Consider running /compact before continuing. ``` ## DATA SOURCES | Check | Source Path | |-------|-------------| | Commands | `~/.claude/commands/grid/` | | Agents | `~/.claude/agents/grid-*.md` | | VERSION | `~/.claude/commands/grid/VERSION` | | State | `.grid/STATE.md` | | Config | `.grid/config.json` | | Budget | `.grid/budget.json` | | Hooks | Grid installation `hooks/` directory | ## RELATED COMMANDS - `/grid:status` - Show current mission progress - `/grid:init` - Initialize or reinitialize Grid state - `/grid:help` - Show all available commands End of Line.