diagnose
Use when diagnosing why a Home Assistant automation, script, device, or integration failed or misbehaved — root-cause analysis from error logs, system logs, traces, and bounded history through HA NOVA Relay. For current home status use ha-nova:health; for plain timelines use ha-nova:history.
markusleben · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add markusleben/ha-nova --skill diagnose技能说明
name: diagnose description: Use when diagnosing why a Home Assistant automation, script, device, or integration failed or misbehaved — root-cause analysis from error logs, system logs, traces, and bounded history through HA NOVA Relay. For current home status use ha-nova:health; for plain timelines use ha-nova:history. license: MIT compatibility: Requires the ha-nova CLI (run 'ha-nova setup' first) and the HA NOVA Relay in Home Assistant (App, or standalone container on Container/Core).
HA NOVA Diagnose
Scope
Root-cause a concrete failure: "why did X not run", "why did X misbehave", "what broke last night".
- Evidence sources: automation/script traces, HA error log, system log, bounded logbook/history windows, template probes, integration diagnostics.
- Boundary:
ha-nova:healthreports CURRENT home status (repairs, unavailable entities);ha-nova:historyanswers plain timeline questions;ha-nova:reviewaudits config quality without a concrete incident. This skill starts from a concrete symptom. - The ONLY mutation in this skill is a temporary
logger.set_leveldebug escalation (see Flow step 5) — every other fix hands off to the owning skill (ha-nova:write,ha-nova:helper,ha-nova:service-call,ha-nova:integration-setupfor credential recovery).
Bootstrap (once per session)
Read and follow ../ha-nova/session-bootstrap.md.
Verify relay CLI: ha-nova relay health
If this fails: ha-nova setup
Relay Contract
File-based relay requests only:
ha-nova relay core --method GET --path <PATH>for REST reads (--out <result-file>for large output)ha-nova relay core --method POST --path <PATH> --body-file <payload-file>for REST calls with a body (template probes, service calls)ha-nova relay ws --data-file <payload-file>for WS commandsha-nova trace latest <entity_id> --json/ha-nova trace list <entity_id> --json/ha-nova trace get <entity_id> <run_id> --jsonfor run traces (positional entity,automation.<id>orscript.<id>)--jq-file <filter-file>for non-trivial filters
Evidence Sources
| Source | Call | Notes |
|---|---|---|
| Run traces | ha-nova trace latest <entity_id> --json (also trace list <entity_id>, trace get <entity_id> <run_id>) | First stop for automation/script failures: shows the exact step, condition results, and variables |
| System log | WS {"type":"system_log/list"} | PRIMARY log source: structured warnings/errors with counts and sources, works on every install type |
| Error log | GET /api/error_log | 404 on HA OS/Supervised since 2025.11 (the log file moved to journald) — that is normal, not an error; stay with system_log/list. Where the file exists (Container/Core, or re-enabled), see Reading the error log |
| Logbook window | GET /api/logbook/<ISO-start>?end_time=<ISO-end>&entity=<entity_id> | Human-readable events around the incident time |
| State history | GET /api/history/period/<ISO-start>?end_time=<ISO-end>&filter_entity_id=<ids> | What states the involved entities actually had |
| Template probe | ha-nova relay core --method POST --path /api/template --body-file <payload-file> with {"template":"{{ ... }}"} | Evaluate the exact condition/template against live state; the rendered result is the string in .data.body |
| Integration diagnostics | WS {"type":"diagnostics/list"}, then GET /api/diagnostics/config_entry/<entry_id> with --out <result-file> | Deep integration state when an integration itself is the suspect |
| Device diagnostics | GET /api/diagnostics/config_entry/<entry_id>/device/<device_id> with --out <result-file> | One device's slice when a single device misbehaves; resolve the (entry_id, device_id) pair via WS diagnostics/list (only entries with a device-diagnostics handler) — a device can carry several entry ids |
Diagnostics redaction is integration-controlled, so downloads are potentially sensitive and NEVER hit bare stdout — save with --out, extract only relevant fields via relay jq before quoting.
Recency honesty: error_log and system_log/list only cover the time since the last Core restart. For older incidents use logbook/history windows, and say explicitly that live logs no longer reach back that far.
Reading the error log
Only where the log file exists (Container/Core installs; on HA OS/Supervised the user can restore it with ha core options --duplicate-log-file=true followed by ha core rebuild and ha core restart, since 2026.1). The upstream body is plain text, but the relay wraps it in the /core envelope — the whole log is one escaped string in .data.body, so searching the saved file line-wise does not work.
-
ha-nova relay core --method GET --path /api/error_log --out <envelope-file> -
Filter the lines you need with a raw jq read (never dump the whole log):
ha-nova relay jq -r --file <envelope-file> --jq-file <filter-file>with
<filter-file>:.data.body | split("\n")[] | select(test("<entity_or_integration>"; "i"))-ris required for raw text output —relay core --jqdoes not support it, so the filtering happens in this second step. Substitute only anentity_id, domain, or integration slug — never a friendly name, which can contain(,)or|and would break the filter. Even a slug is not literal: the.insensor.kitchenis a regex wildcard, so escape it (sensor\\.kitchen) or the filter also matchessensor_kitchenand reports unrelated lines as evidence.The identifier is the ONLY selector — never OR a severity into it.
test("sensor\\.kitchen|ERROR")matches every error line in the log, from every unrelated integration, and each one then looks like evidence for this incident. To narrow by severity, AND it:select(test("sensor\\.kitchen"; "i") and test("ERROR|WARNING"; "i")). And a log with no matching line is a finding in itself — say the log holds nothing about this entity, rather than widening the filter un