ha-diagnostics-augment

HA Diagnostics Augment

Spec: spec/claude/ha-diagnostics-augment/en.md (EN canonical) / spec/claude/ha-diagnostics-augment/de.md (DE translation).

Why this is a skill, not an agent

• Human-visible augmentation surface — the user describes the integration and reads back diagnostics.py, the TO_REDACT set, and the conformance report; a skill keeps this on the visible command surface, like the sibling augment skills (ha-config-flow-augment, ha-coordinator-add, ha-repairs-add, ha-device-automation-add).
• Mid-flow interactivity — the redaction-key classification (which entry.data fields are credentials/identifiers/coordinates) is a per-run dialogue the user confirms before generation.
• Bounded, inline generation — one module plus its TO_REDACT set and the dump structure fit inline; no isolated agent context is needed.
• Counter-dimension considered: the derive→validate loop could be an agent, but the redaction-key classification belongs in the user's working context; skill wins.

When this skill activates

Use this skill to enrich an existing integration's diagnostics beyond the scaffold baseline — a complete, structured async_get_config_entry_diagnostics dump (and optionally async_get_device_diagnostics) that routes every sensitive field through async_redact_data and includes redacted coordinator snapshots.

When NOT to activate

• auditing redaction gaps across modules (findings report) → ha-security-audit
• the bare diagnostics stub at greenfield creation → ha-integration-scaffold
• scoring the diagnostics quality-scale rule across all rules → ha-quality-scale-audit / ha/quality-scale
• deploying/importing into a running HA instance → out of scope

Hard rules

1. Existing integration only. custom_components/<domain>/manifest.json must exist. When diagnostics.py already exists, edit it — never blindly overwrite.
2. Read spec/ha/diagnostics/en.md first. Do not generate from memory.
3. async_get_config_entry_diagnostics contract. Export async_get_config_entry_diagnostics(hass, entry) -> dict as a top-level async function — HA invokes it automatically on "Download Diagnostics". Optionally export async_get_device_diagnostics(hass, entry, device) -> dict with the same redaction contract.
4. async_redact_data is mandatory. Wrap every entry.data and entry.options lookup — and every coordinator nesting that carries sensitive fields — in homeassistant.components.diagnostics.async_redact_data(..., TO_REDACT). Never use manual logic (if "api_key" in d: d["api_key"] = "***"), a manual "REDACTED" string, or field deletion (del d["api_key"]); **REDACTED** preserves length/format debugging and is the HA convention.
5. Module-constant TO_REDACT frozenset. Define TO_REDACT as a module constant (or in const.py when shared across hooks) holding every entry.data key classified as a credential or identifier — typically api_key, password, token, secret, auth, bearer, plus integration-specific tenant/account slugs. Keep it in sync with the entry.data schema.
6. Identifiers and coordinates too. Include multi-tenant identifiers (tenant_slug, tenant_id, org_id) and coordinates (latitude, longitude) in TO_REDACT — identifying, therefore kept out of forum reports.
7. Coordinator data in the dump. Include the current coordinator.data of every registered coordinator and redact it when the API response carries sensitive fields; reduce to a subset only when the full dump would be too large. Never dump logs or stack traces.
8. Derive, don't guess. Derive the entry.data / entry.options key space from the config flow and setup; ask when uncertain.
9. Name per spec/ha/naming-conventions/en.md and verify HA internals against the official docs (see spec/ha/upstream-docs-verification/en.md).