brycewang-stanford/doctor

Diverga Doctor

Version: 11.1.0 Trigger: /diverga:doctor

Description

System diagnostics for the Diverga plugin. Checks plugin health, skill sync, hook enforcement, configuration validity, API keys, and project state. Reports issues with actionable fix commands.

Follows OpenClaw Check-Report-Fix pattern: every detected issue includes a fix recommendation.

Instructions

When user invokes /diverga:doctor, execute all 7 diagnostic layers sequentially and display results.

Layer 1: Plugin Health

Check plugin registration:

• Read ~/.claude/plugins/installed_plugins.json
• Verify diverga@diverga entry exists
• Extract version and install date

Check config JSON validity:

• Read ~/.claude/plugins/diverga/config/diverga-config.json
• Verify it parses as valid JSON
• Check required fields exist: version, human_checkpoints, language

Report format:

PLUGIN HEALTH
  Registration:    [PASS - diverga@diverga v11.1.0 | FAIL - not found in installed_plugins.json]
  Config file:     [PASS - valid JSON | FAIL - missing or invalid]
  Config fields:   [PASS - all required fields present | WARN - missing: field1, field2]

Fix if FAIL:

• Registration missing: "Run: /plugin install diverga"
• Config missing: "Run: /diverga:setup to regenerate configuration"
• Config invalid JSON: "Config file is corrupted. Run: /diverga:setup to regenerate"

Layer 2: Skill Sync

Check skill counts match between plugin and local cache:

• Use Glob to count directories in ~/.claude/plugins/diverga/skills/*/SKILL.md
• Use Glob to count directories in ~/.claude/skills/diverga-*/SKILL.md (exclude diverga-diverga prefix duplication — count unique skill names)
• Compare counts

Check for missing skills in local cache:

• For each skill in plugin directory, check if corresponding diverga-{name} exists in local skills
• List any missing skills

Report format:

SKILL SYNC
  Plugin skills:   [count] skills in plugin directory
  Local skills:    [count] skills in local cache
  Sync status:     [PASS - all synced | WARN - X skills missing locally]
  Missing:         [list of missing skill names, if any]

Fix if WARN:

• "Missing local skills. To resync, reinstall the plugin or manually copy:"
• For each missing skill: " cp -r ~/.claude/plugins/diverga/skills/{name} ~/.claude/skills/diverga-{name}"

Layer 3: Plugin Cache Sync

Check that the plugin cache matches the installed version:

• Read ~/.claude/plugins/diverga/plugin.json → extract version
• Glob ~/.claude/plugins/cache/diverga/diverga/*/plugin.json → list cached versions
• Compare: cached version should match installed version
• Check if cached version has hooks/hooks.json

Report format:

PLUGIN CACHE
  Installed version: [11.1.0 | FAIL - plugin.json missing]
  Cached version:    [11.1.0 | WARN - stale cache: 8.0.1 | FAIL - no cache found]
  Cache has hooks:   [PASS - hooks.json present | FAIL - hooks missing from cache]
  Cache has agents:  [PASS - agents/ present | WARN - agents/ missing]

Fix if WARN/FAIL:

• Stale cache: "Plugin cache is outdated. Run in terminal:"

  REPO="/Volumes/External SSD/Projects/Diverga/Diverga-core"
  CACHE="$HOME/.claude/plugins/cache/diverga/diverga/11.1.0"
  rm -rf "$HOME/.claude/plugins/cache/diverga/diverga/8.0.1"
  mkdir -p "$CACHE"
  cp -R "$REPO"/{skills,agents,config,hooks,mcp,CLAUDE.md,AGENTS.md,README.md} "$CACHE/"
  cp "$REPO/.claude-plugin/plugin.json" "$CACHE/"
  

• No hooks in cache: "Copy hooks manually: cp -R ~/.claude/plugins/diverga/hooks/ $CACHE/hooks/"
• Restart Claude Code after cache update for changes to take effect

Layer 4: Hook Enforcement

Check hook configuration:

• Read ~/.claude/plugins/diverga/hooks/hooks.json → verify it exists and has PreToolUse entries
• Check matchers include "Agent" and "Skill" (not "Task" — known bug in pre-11.1.0)
• Read ~/.claude/settings.json → check if hooks are also configured at global level
• Test hook execution: Run echo '{"tool_name":"Skill","tool_input":{"skill":"diverga:c1"}}' | node ~/.claude/plugins/diverga/hooks/prereq-enforcer.mjs → verify it returns valid JSON with continue field

Report format:

HOOK ENFORCEMENT
  Plugin hooks.json: [PASS - exists with Agent+Skill matchers | FAIL - missing or wrong matchers]
  Global hooks:      [PASS - configured in settings.json | WARN - not in settings.json (relies on plugin)]
  Hook executable:   [PASS - returns valid JSON | FAIL - execution error]
  Matcher check:     [PASS - uses "Agent" | FAIL - uses stale "Task" matcher]

Fix if issues found:

• Wrong matcher: 'Change "Task" to "Agent" in hooks.json — Claude Code uses "Agent" as tool name'
• Not in settings.json: "Add hooks to ~/.claude/settings.json for reliable enforcement across sessions"
• Execution error: "Check that better-sqlite3 is installed: cd ~/.claude/plugins/diverga/mcp && npm install"

Layer 5: Config Validity

Deep validation of diverga-config.json:

• Read ~/.claude/plugins/diverga/config/diverga-config.json
• Check version field matches "11.1.0"
• Check human_checkpoints object exists and has enabled (boolean) and required (array)
• Check language is one of: "en", "ko", "auto"
• Check model_routing has high, medium, low keys if present

Report format:

CONFIG VALIDITY
  Version field:   [PASS - 11.1.0 | WARN - version mismatch: found X.Y.Z]
  Checkpoints:     [PASS - configured | FAIL - missing or malformed]
  Language:        [PASS - "en" | WARN - unexpected value: "XX"]
  Model routing:   [PASS - configured | SKIP - not set (using defaults)]

Fix if issues found:

• Version mismatch: "Config version X.Y.Z doesn't match plugin 11.1.0. Run: /diverga:setup to update"
• Checkpoints malformed: "Run: /diverga:setup to reconfigure checkpoints"

Layer 6: API Keys

Check 8 environment variables using Bash tool (echo $VAR_NAME):

| Variable | Purpose | Required? | |----------|---------|-----------| | GROQ_API_KEY | LLM screening (recommended) | Recommended | | ANTHROPIC_API_KEY | Claude API | Recommended | | OPENAI_API_KEY | OpenAI screening | Optional | | GEMINI_API_KEY | Gemini visualization | Optional | | SEMANTIC_SCHOLAR_API_KEY | Paper retrieval | Optional | | OPENALEX_EMAIL | OpenAlex polite pool | Optional | | SCOPUS_API_KEY | Scopus access | Optional | | WOS_API_KEY | Web of Science | Optional |

For each variable, use Bash: echo "${VAR_NAME:+configured}" — if output is "configured", it's set; if empty, it's not set.

Report format:

API STATUS
  Groq:              [configured | NOT SET -> export GROQ_API_KEY=your_key]
  Anthropic:         [configured | NOT SET -> export ANTHROPIC_API_KEY=your_key]
  OpenAI:            [configured | not set (optional)]
  Gemini:            [configured | not set (optional)]
  Semantic Scholar:  [configured | not set (optional)]
  OpenAlex:          [configured | not set (optional)]
  Scopus:            [configured | not set (optional)]
  Web of Science:    [configured | not set (optional)]

Fix if NOT SET (recommended keys):

• Show export VAR_NAME=your_key_here for each missing recommended key
• For optional keys, just note "(optional)" — no urgent fix needed

Layer 7: Project State

Check for active research project:

• Use Glob to check if .research/project-state.yaml exists in current working directory
• If exists: Read it and validate YAML structure (has project_name, current_stage)
• Also check if .research/ directory exists with expected subdirectories

Report format:

PROJECT STATE
  Active project:  [project name | No active project]
  State file:      [PASS - valid | WARN - invalid YAML | SKIP - no project]
  Research dir:    [PASS - structure intact | WARN - missing subdirs | SKIP - no project]

Fix if issues:

• Invalid YAML: "Project state file is corrupted. Run: /diverga:setup in your project directory"
• Missing subdirs: "Run: /diverga:setup to reinitialize project structure"
• No project: "Start a new project with: /diverga:setup or describe your research topic"

Final Summary

After all 7 layers, display overall status:

══════════════════════════════════════════════
DIVERGA SYSTEM DIAGNOSTICS v11.1.0
══════════════════════════════════════════════

[Layer 1-7 results as shown above]

------------------------------------------
OVERALL: [HEALTHY | X WARNING(S) | X ERROR(S)]

[If issues found, numbered list:]
  1. [Issue description] -> [Fix command]
  2. [Issue description] -> [Fix command]
  ...

[If healthy:]
  All systems operational. Diverga is ready to use.
  Run /diverga:help to see all 24 agents and commands.
══════════════════════════════════════════════

Implementation Notes

• Execute all Bash commands for API key checks in PARALLEL (single message, multiple Bash calls)
• Use Read tool for JSON/YAML file checks
• Use Glob tool for skill counting
• This skill is READ-ONLY — it does not modify any files
• If any individual check encounters an error (file not readable, etc.), show "UNABLE TO CHECK" rather than crashing
• Total execution target: under 10 seconds