/naksha-doctor

description: "Run all naksha quality checks and report the plugin's health status."
argument-hint: "[--fix]"
allowed-tools: ["Bash", "Read", "Glob", "mcp__plugin_playwright_playwright__browser_navigate", "mcp__figma-console__figma_get_status", "mcp__stitch__list_projects"]

/naksha-doctor

Run a full health check of the naksha plugin — structural validation, metadata consistency, behavioral smoke, and legacy branding guard. Report each check as ✅ PASS or ❌ FAIL with specific remediation for any failures.

Arguments

• No argument: run all checks and show the status report
• `--fix`: after showing failures, output step-by-step remediation instructions for each failed check

Step 1: Locate the plugin root

Use `Glob` to find `meta/stats.json` — the directory containing it is the plugin root. All scripts are in `scripts/` relative to that root. Change to that directory before running scripts.

Step 2: Run all quality checks

Run each script separately so results can be attributed individually. Capture output and exit code for each:

node scripts/validate-structure.js 2>&1

bash scripts/verify-metadata.sh 2>&1

bash scripts/behavioral-smoke.sh 2>&1

bash scripts/guard-legacy-branding.sh 2>&1

Step 2.5: MCP Availability Check

Probe the two primary MCP integrations that naksha commands depend on. These checks are **informational** — they reveal whether MCP-dependent commands will work in the current environment. MCP unavailability does not make the plugin unhealthy; it means certain commands will operate in fallback mode.

**Playwright MCP:** Attempt to call `mcp__plugin_playwright_playwright__browser_navigate` with `url: "about:blank"`.

• If the call succeeds → record `AVAILABLE`
• If the tool throws an error or is not found → record `UNAVAILABLE`

**Figma MCP:** Attempt to call `mcp__figma-console__figma_get_status`.

• If the call succeeds → record `AVAILABLE`
• If the tool throws an error or is not found → record `UNAVAILABLE`

**Stitch MCP:** Attempt to call `mcp__stitch__list_projects`.

• If the call succeeds → record `AVAILABLE`
• If the tool throws an error or is not found → record `UNAVAILABLE`

Record all three results for inclusion in the health report.

Step 2.6: Project Memory Check

Look for `.naksha/project.json` in the current directory and up to 3 parent directories.

• **Not found** → record `NO_PROJECT` (informational — the plugin may be running outside a project directory)
• **Found, has `schema_version: "5"`** → record `V5`
• **Found, missing `schema_version`** → record `V4` (v4 project — eligible for v5 upgrade)

Record this result for the health report. This check is **informational** — v4 projects are valid, they just lack v5 memory features.

Step 2.7: Reel Toolchain Check

Probe the toolchain `/design-reel` needs to render video. **Informational** — its absence does not make the plugin unhealthy; it means `/design-reel` is unavailable until set up.

command -v node >/dev/null 2>&1 && echo "node $(node -v)" || echo "node MISSING"
command -v ffmpeg >/dev/null 2>&1 && echo "ffmpeg OK" || echo "ffmpeg MISSING"
[ -d packages/naksha-reel/node_modules ] && echo "reel-deps INSTALLED" || echo "reel-deps NOT_INSTALLED"

• All present → record `READY`.
• node or ffmpeg missing → record `UNAVAILABLE` (cannot render).
• node + ffmpeg present but `reel-deps NOT_INSTALLED` → record `SETUP_NEEDED` (one-time

`npm install` in `packages/naksha-reel`, done automatically on first `/design-reel` run).

When not `READY`, add this line to the report's Note section: `Note: /design-reel requires Node + ffmpeg + packages/naksha-reel. See docs/reel-setup.md.`

Step 3: Build the health report

Parse each script's output and exit code. Present results in this format when all quality checks pass:

╔═══════════════════════════════════════╗
║       naksha doctor                   ║
╚═══════════════════════════════════════╝

  ✅  validate-structure    8/8 checks passed
  ✅  verify-metadata       all counts consistent
  ✅  behavioral-smoke      fixtures passing
  ✅  guard-legacy-branding no banned strings found

  ──────────────────────────────────────
  MCPs         playwright  ✅ AVAILABLE
               figma       ✅ AVAILABLE
               stitch      ✅ AVAILABLE
  ──────────────────────────────────────
  Memory       schema      ✅ v5 (project.json found)
  ──────────────────────────────────────
  Reel         toolchain   ✅ READY (/design-reel)
  ──────────────────────────────────────

  ══════════════════════════════════════
  Status: HEALTHY — 4/4 checks passed
  ══════════════════════════════════════

Show the Reel row from the Step 2.7 result: `READY` → `✅ READY (/design-reel)`; `SETUP_NEEDED` → `⚠ setup needed — npm install runs on first /design-reel`; `UNAVAILABLE` → `❌ UNAVAILABLE — node/ffmpeg missing (see docs/reel-setup.md)`.

Show the Memory row based on Step 2.6 result:

• `V5` → `✅ v5 (project.json found)`
• `V4` → `⚠ v4 — run /naksha-doctor --fix to upgrade to v5`
• `NO_PROJECT` → `ℹ no project.json — run /naksha-init to set up`

When any quality check fails, show ❌ and a one-line summary. The HEALTHY/UNHEALTHY status and N/4 count is based on script checks only — MCP and memory availability are shown separately as environment probes:

╔═══════════════════════════════════════╗
║       naksha doctor                   ║
╚═══════════════════════════════════════╝

  ✅  validate-structure    8/8 checks passed
  ❌  verify-metadata       FAIL — commands count mismatch
  ✅  behavioral-smoke      fixtures passing
  ✅  guard-legacy-branding no banned strings found

  ──────────────────────────────────────
  MCPs         playwright  ❌ UNAVAILABLE
               figma       ✅ AVAILABLE
               stitch      ✅ AVAILABLE
  ──────────────────────────────────────
  Note: /design-compare, /competitive-audit require Playwright.
  These commands will fall back to manual screenshot mode.
  ────