diagnose

# /diagnose — Pi Troubleshooting Runbook Produce a structured diagnostic plan when the Pi misbehaves. The actual commands and known-failure signatures live in the code (`scripts/setup.sh` defines the units; `can_reader.py`, `sk_reader.py`, `audio.py`, `storage.py` each document their own failure modes); read those rather than duplicating them here. This skill specifies the **runbook shape** — phases, status tags, dependency rules, summary format. ## Usage - `/diagnose` — run all subsystem checks - `/diagnose <subsystem>` — one of: `system`, `services`, `can`, `signalk`, `audio`, `database`, `network`, `aihat`. Argument is `$ARGUMENTS`. ## Status tags (use these exact strings) ``` [OK] <check> — <detail> [WARN] <check> — <detail> → <suggested fix> [FAIL] <check> — <detail> → <suggested fix> [SKIP] <check> — skipped because <dependency> is <state> ``` Every check produces exactly one status line. Group commands under the check, but the status line is what the operator scans. ## Dependency graph (skip rules) ``` System Health └── Services (skip if filesystem read-only) ├── CAN Bus (skip if helmlog service down — runs in-process) ├── Signal K (skip if signalk service down) ├── Audio (skip if helmlog service down — runs in-process) └── AI HAT (skip if helmlog service down — runs in-process) Database (independent — always run) Network (independent — always run) ``` **Key fact:** CAN ingest, Signal K subscription, audio capture, and the FastAPI app all live inside the `helmlog` process. If `helmlog` is inactive, those checks have no consumer to observe — mark `[SKIP]` with that reason, do not attempt them. If a parent check fails, emit `[SKIP]` for every dependent and continue; never silently omit a subsystem. ## Phasing (when helmlog is down) When the request is a full diagnosis and `helmlog` is inactive, run in three phases — do not interleave: 1. **Independent checks first** — system health, database, network. These tell you whether the host is healthy enough to run the app at all. 2. **Inspect why helmlog is inactive, then restart** — `systemctl status`, `journalctl -u helmlog -n 80`, match against known failure signatures (most common: `ModuleNotFoundError` from a stale venv after `git pull` — the service runs `--no-sync`). Restart and confirm `is-active`. 3. **Dependent checks only after helmlog is active.** Until then, every in-process subsystem is `[SKIP]`. For partial outages (helmlog active but a specific subsystem failing), phasing is unnecessary — just walk the dependency graph. ## Summary format (always emit at the end) ``` === /diagnose summary === Total checks: N [OK] N [WARN] N [FAIL] N [SKIP] N Most likely root cause: <one sentence, derived from the failure pattern> Recommended next action: <one command or one decision> ``` If there are no failures, omit the root-cause line and emit `No failures — system is healthy`. ## Out of scope - Does not modify code, configs, or services. - Does not run lint/tests/type checks. - Does not deploy. Use `/deploy-pi` for that. - AI HAT is not yet deployed; `[OK] AI HAT — not installed (expected)` is the expected outcome until that changes.