mtk-doctor

name	mtk-doctor
description	Run an MTK install health check (core files, components, hooks, integrity) with PASS/WARN/FAIL diagnostics, --json for CI, and --fix for safe auto-repairs.

MTK Doctor

Overview

mtk-doctor is the holistic health check for an MTK installation. Where validate-toolkit.sh checks structural integrity (manifest matches files, frontmatter shape), the doctor catches runtime rot: deprecated model IDs in agents, oversized CLAUDE.md, missing gitignore entries, stale analytics, dangling hook registrations.

When To Use

• Periodically (e.g. before bumping the toolkit version)
• When the engineer asks "is the toolkit healthy?" or "is anything broken?"
• After upgrading MTK in a target repo (catch deprecated IDs and hook drift)
• In CI as bash scripts/mtk-doctor.sh --strict --json for dashboards

When NOT To Use

• For structural validation in tight loops — use validate-toolkit.sh (faster, focused).
• To debug a specific failing skill — use context-report instead.

Workflow

1. Run the script. Default: human-readable output.

   bash scripts/mtk-doctor.sh
   

2. Apply safe fixes. Auto-fix gitignore additions and chmod issues:

   bash scripts/mtk-doctor.sh --fix
   

   FAILs are never auto-fixed. Auto-fix is for known-safe items only.

3. CI mode. Strict + JSON:

   bash scripts/mtk-doctor.sh --strict --json
   

   Strict treats WARN as failure (exit 1). JSON output suits dashboards.

4. Triage failures. Each FAIL entry includes a detail field pointing at the fix path. Common cases:

   • "version mismatch" → bump both manifest.json and plugin.json (and marketplace.json) to the same value
   • "deprecated model" → update agent frontmatter to a current model ID
   • "hook missing" → either add the hook script or remove its registration from settings.json
   • "skill name mismatch" → rename the directory or update frontmatter name: to match

Categories Checked

• CORE — required files (manifest, plugin.json, README, AGENTS, validate-toolkit), CLAUDE.md line budget if present
• COMPONENTS — version sync, skill counts, skill name/directory consistency, deprecated model detection
• HOOKS — registered hooks exist and are executable, event names valid, all hooks use set -euo pipefail
• INTEGRITY — manifest paths exist, gitignore coverage, analytics freshness, validate-toolkit passes
• CONTEXT — always-on context baseline (CLAUDE.md + rules/INDEX.md + alwaysApply refs, in tokens/bytes), MCP schema count from .mcp.json, ENABLE_TOOL_SEARCH state (report-only, never WARN/FAIL)

Verification

• Output shows non-zero PASS in every category (no empty section)
• Summary line printed last
• Exit code 1 on any FAIL
• --strict exits 1 on WARN
• --json output is valid JSON parseable by jq
• --fix only modifies gitignore and file permissions; never edits source files

Red Flags

• Doctor reports PASS when validate-toolkit.sh fails — checks are out of sync
• --fix modifies source code or skill content (it shouldn't — only gitignore + chmod)
• New checks added that overlap with validate-toolkit.sh — keep validator structural, doctor holistic
• Deprecated model list goes stale — update DEPRECATED_MODELS in scripts/mtk-doctor.sh when Anthropic deprecates more