AGENT SKILL

ha-quality-review

Perform a structured quality review of this Home Assistant custom integration, either as a full audit or scoped to a diff. Use when asked to "review the integration", "audit the code", "check quality scale", "are we bronze/silver/gold", "is this ready to release", "review my changes", "what's missing before publishing", or before opening a pull request that touches integration code. Covers running the automated gates first, then auditing architecture, the Integration Quality Scale rules, error handling, security, performance, user experience, and documentation — and reporting findings ranked by severity with concrete fixes. SYMPTOMS — load this if you are about to: report a review that only restates linter output; claim real-device testing that did not happen; give a finding without a file path and a fix; or judge quality without running `script/hassfest` and the test suite first.

License 许可
MIT
所属仓库
amg0/ha_ksenia
最近更新
2026-11-15
Stars
★ 0
Forks
0

01 前言 Front Matter

name
ha-quality-review
description
Perform a structured quality review of this Home Assistant custom integration, either as a full audit or scoped to a diff. Use when asked to "review the integration", "audit the code", "check quality scale", "are we bronze/silver/gold", "is this ready to release", "review my changes", "what's missing before publishing", or before opening a pull request that touches integration code. Covers running the automated gates first, then auditing architecture, the Integration Quality Scale rules, error handling, security, performance, user experience, and documentation — and reporting findings ranked by severity with concrete fixes. SYMPTOMS — load this if you are about to: report a review that only restates linter output; claim real-device testing that did not happen; give a finding without a file path and a fix; or judge quality without running `script/hassfest` and the test suite first.

02 资源文件 2

03 SKILL.md 正文

Review the integration

A review that only restates the linter is worthless. Run the machines first, then spend your attention on what they cannot see: layering, failure behaviour, and whether a user would understand what this integration does.

0. Scope the review

Ask, or infer from the request:

  • Full audit of the integration, or diff review of the current branch?
  • Is there a target tier (this project aims for Silver, ideally Gold)?

For a diff review: git diff main...HEAD --stat, then read the changed files in full — not just the hunks.

When the diff is an open pull request, read what others already said before adding to it: gh pr view <number> --comments and gh api repos/{owner}/{repo}/pulls/<number>/comments for the inline ones. Every earlier finding — a human's, a bot's, another agent's — is either fixed in the current head, answered in the thread, or still open; report the open ones instead of rediscovering them, and do not repeat what was already settled.

1. Automated gates (always first)

script/lint          # ruff format+fix, shfmt, prettier/markdownlint, yamllint, zizmor, shellcheck
script/type-check    # pyright — never auto-fixed
script/hassfest      # manifest, services.yaml, translations, integration structure
script/test --cov-html

Anything these report is a finding, not something to fix silently mid-review — but do note that script/lint already auto-heals formatting, so only its remaining output counts.

2. Architecture

  • Layering is Entity → Coordinator → source. Any entity importing api/ directly, or any coordinator holding HTTP details, is a finding.
  • Package structure matches the fixed set (api/, coordinator/, config_flow_handler/, entity/, entity_utils/, <platform>/, service_actions/, utils/). A helpers/, common/, shared/, or lib/ package is a finding.
  • Files are 200–400 lines, one entity class per file.
  • Runtime state lives in entry.runtime_data, never hass.data[DOMAIN].
  • No circular imports; TYPE_CHECKING guards for type-only imports.

Two upstream requirements this project deliberately does not meet. Neither is a finding here, and both should be stated as decisions rather than silently passed over:

  • Core requires all device or service communication to be wrapped in a PyPI library. As a custom integration this project allows an in-repo client (AGENTS.md § Custom Integration Flexibility) — with the consequence that the client would have to be extracted before this could ever be submitted to Core.
  • Core wants the coordinator in coordinator.py, the base entity in entity.py and actions in services.py. This project's coordinator/, entity/ and service_actions/ packages are the accepted equivalents.

3. Quality scale audit

File When to read
references/quality-scale-rules.md Auditing a tier. All 54 rule identifiers with one-line criteria, grouped by tier.

Walk the rules for the target tier and report each as pass / fail / not applicable. For every fail, name the file and the fix.

Home Assistant reports every custom integration's tier as custom, whatever quality_scale in the manifest says, so the tier is a self-assessment, not something Home Assistant checks. A claimed Silver or above still needs at least one entry in codeowners (integration-owner).

The rules most often missed in this codebase's shape:

  • action-setup — actions registered in async_setup(), not per entry.
  • parallel-updates — every platform package's __init__.py defines PARALLEL_UPDATES at module level: 0 on a read-only coordinator platform, a value the device can take on platforms that send commands.
  • entity-translations / icon-translations — no hardcoded name= or icon= in EntityDescription.
  • exception-translations — no English strings inside raised exceptions.
  • log-when-unavailable — the coordinator must not log on every failed poll.
  • entity-category / entity-disabled-by-default — diagnostics entities are marked and often disabled by default.
  • stale-devices / dynamic-devices — devices appear and disappear with upstream reality.

4. Code quality

File When to read
references/core-lint-checks.md Any review of integration code. The integration-specific checks Home Assistant Core lints in its own CI and this repository cannot run.

Look for the failure modes linters miss:

  • Typing — full annotations, -> None on procedures, no bare Any where a TypedDict or dataclass is meant, no from __future__ import annotations (banned on Python 3.14).
  • Async — no blocking I/O in the event loop (requests, open(), time.sleep, sync SDK calls); every network call has a timeout; asyncio.timeout rather than a deprecated helper.
  • Exceptions — specific types, never bare except:; raise ... from err to preserve the chain; the coordinator translates client exceptions into UpdateFailed / ConfigEntryAuthFailed correctly.
  • Properties — no I/O, no raising, no side effects.
  • Constants — no magic numbers or duplicated strings; reuse homeassistant.const names.
  • Logging — lazy %s formatting, debug for the normal path, no secrets in any log line at any level.

Patterns Core reviewers catch that no tool does:

  • Signs of unreviewed AI output — fixes for problems that do not exist, defensive code for conditions that cannot happen, test fixtures changed without a change in behaviour, or a polished description on top of code that shows a basic misunderstanding. Agent-written code in this repository is held to the same test.
  • Truthiness on device values — bool(value) or int(value) on something that can be None or a string: bool(None) turns a missing value into "off", and bool("0") is True. Convert explicitly (value == "1").
  • entry.runtime_data read where setup may have failed — error paths, unload, and anything iterating async_entries(). It is set only for a loaded entry; use async_loaded_entries() and handle none.
  • Lifecycle boundaries — every listener, timer and connection opened in setup or async_added_to_hass is released through entry.async_on_unload / self.async_on_remove, and connections also close on Home Assistant stop. A try that wraps everything is not a fix; small try blocks around the call that can raise are.

5. Security

Check each; the rule and how to comply live in the linked file.

  • Credentials only in entry.data, and the data/options split right for config-flow — blueprint.config_flow.
  • Diagnostics redact the whole payload, and TO_REDACT still matches the API response — blueprint.diagnostics.
  • TLS verification on by default; a CONF_VERIFY_SSL option defaults to True, and no secret has a schema default.
  • Log lines mask keys and IDs with partial_redact() — blueprint.python.
  • Admin-only actions, and caller-supplied paths checked with is_allowed_path() — blueprint.service_actions.
  • Webhooks called from the LAN are local_only — blueprint.coordinator.
  • Data from a device or service never reaches eval(), exec() or a shell.
  • Dependencies pinned identically in manifest.json and requirements.txt, and reviewed for supply-chain risk — blueprint-tooling.

6. Performance

  • One coordinator poll serves all entities; no per-entity API calls.
  • Interval appropriate for the source (ha-coordinator-debug), a constant — a polling-interval field is a finding (blueprint.config_flow), and removing one users already set goes through ha-breaking-changes.
  • No unnecessary async_write_ha_state(); no work in __init__.
  • Data structures let entities read by key rather than scanning lists.

7. User experience

  • Config flow validates before creating the entry and shows recoverable, translated errors.
  • Entity names read well in the UI with has_entity_name (no repeated device name).
  • Units, device classes, and state classes are set so history and statistics work.
  • Failures surface as repair issues or reauth flows rather than silent unavailability.
  • For an integration that depends on a remote endpoint, consider system_health.py: a @callback async_register that calls register.async_register_info(...), whose info callback returns a dict whose values may be coroutines (the frontend shows a spinner and resolves them). system_health.async_check_can_reach_url(hass, ENDPOINT) covers the common case, and every key needs a system_health.info.<key> translation. It turns "it is broken" into "the API is unreachable" on the user's own system page.

8. Documentation and release hygiene

  • README.md, docs/user/ describe what actually exists — not the blueprint's placeholder text.
  • The docs-* rules are met by the integration's own documentation — which file covers which rule: quality-scale-rules.md.
  • manifest.json: correct integration_type, iot_class, documentation, issue_tracker, codeowners, version.
  • Publishing readiness, when it is meant to be listed — repository preconditions, brand images, the CI gates the catalog requires: ha-marketplace has the checklist.
  • Architectural choices worth remembering are in docs/development/DECISIONS.md (ha-planning).
  • Breaking changes carry a migration path (ha-breaking-changes).

Report format

Rank by severity and be specific. A finding without a file path and a fix is noise.

## Summary

<2–3 sentences: overall state, current effective tier, biggest risk.>

## Critical — must fix before release

### 1. <Title>

- **Where:** `custom_components/<domain>/coordinator/base.py:82`
- **Problem:** <what is wrong and what it breaks for a user>
- **Fix:** <concrete change>

## Warnings — should fix

## Suggestions — nice to have

## Quality scale

| Tier | Status | Failing rules |
| ---- | ------ | ------------- |

## Verified

<What you actually ran, and what you could not verify — e.g. no real device available.>

Be honest in the last section. Do not describe checks you did not run, and do not imply real-device testing happened when it did not — that is an explicit rule of this project's AI_POLICY.md.

Verify each finding by running something — a gate, a test, a grep of the installed Home Assistant source — rather than from memory or from how the code reads. A finding you could not verify that way stays in the report, marked unverified, with what would confirm it.

After the review

Report findings; do not silently fix them unless the developer asked for fixes. If they did, fix in severity order, run script/lint && script/type-check && script/test after each group, and state what you changed.

04 同仓库更多 Skills

amg0
amg0/ha_ksenia

issues

Triage/fix the GitHub issue backlog via branch + PR, with auto-merge on green CI for this session.

★ 0
amg0
amg0/ha_ksenia

ha-translations

Add or fix user-facing strings for this Home Assistant custom integration — translations/en.json and other languages, icons.json, entity names and states, config flow labels and errors, service action descriptions, exception messages, and repair issue text. Use when asked to "update translations", "add a translation key", "translate", "fix the entity name", "add strings for the new sensor/action/option", "add icons", or when hassfest reports a missing or unused translation key. Covers the key structure, which keys each feature needs, placeholders, the icons.json contract, and the project's strict rule about only touching en.json. SYMPTOMS — load this if you are about to: write user-facing English into Python; edit a language file other than `en.json`; add an entity without its `entity.<platform>.<key>.name` key; skip `data_description` on a config flow field; or set `icon=` instead of using `icons.json`.

★ 0
amg0
amg0/ha_ksenia

ha-testing

Write, fix, or extend automated tests for this Home Assistant custom integration using pytest and pytest-homeassistant-custom-component. Use when asked to "add tests", "write a test", "the tests fail", "improve coverage", "add a regression test", "test the config flow", "update snapshots", or when a behavioural change needs verification before it can be called done. Covers the tests/ layout, the conftest.py fixtures this project needs, mocking the API client, config flow and entity test patterns, registry assertions, syrupy snapshots, freezing time, and the script/test commands. SYMPTOMS — load this if you are about to: instantiate an entity class directly instead of asserting on `hass.states`; write a test without `enable_custom_integrations`; use `time.sleep` instead of `async_fire_time_changed`; silence a DeprecationWarning to make the suite pass; or commit a snapshot you have not read.

★ 0
amg0
amg0/ha_ksenia

ha-service-action

Add, change, or remove a Home Assistant service action (also called a "service" or "action") in this custom integration. Use when asked to "add a service", "add an action", "expose X as a service call", "add a service that returns data", "make this callable from an automation", or when editing services.yaml, the service_actions/ package, service schemas, service response data, or the async_setup() registration. Covers the services.yaml contract, probatio schemas, selectors, entity/device targeting, response data, translated error messages, and the Bronze quality-scale rule that actions must be registered in async_setup(). SYMPTOMS — load this if you are about to: register an action in `async_setup_entry()`; add a `services.yaml` field without a selector; add an `entity_id` field where `target:` belongs; raise a plain English `HomeAssistantError`; or swallow an action failure into a log line.

★ 0
amg0
amg0/ha_ksenia

ha-release

Cut a release of this Home Assistant custom integration, or prepare the commits that feed it. Use when asked to "release", "cut a version", "bump the version", "prepare release notes", "what will the next version be", "write a commit message", "why didn't release-please pick this up", or when reviewing whether a change is user-facing. Covers the Conventional Commits rules commitlint enforces here, how release-please derives the version and changelog, the pre-1.0 bump rules, script/version and script/release-notes, skipping a commit from the notes, and the commit rules this project enforces for agents. SYMPTOMS — load this if you are about to: commit without an explicit request; offer to `git push`; label a user-facing fix as `chore` (chore, like every hidden type, never reaches the changelog and never triggers a release); write a commit subject over 100 characters or in sentence case; or edit the version in `manifest.json` by hand.

★ 0
amg0
amg0/ha_ksenia

ha-planning

Plan a large change to this Home Assistant custom integration before writing code, or record an architectural decision. Use when asked to "create a plan", "plan this feature", "how should we approach", "propose an architecture", "write an ADR", "document this decision", "should we use library X or write our own client", or whenever a change would touch more than about ten files or alter the integration's structure. Covers when a plan is mandatory, the phased plan format, where plans live, when a decision is worth recording, and the DECISIONS.md entry format used by this project. SYMPTOMS — load this if you are about to: start a refactor spanning more than ten files without confirmation; write a plan whose phases name no files; write one in prose nobody will finish reading; create a planning markdown file outside `.agents/scratch/`; or make a hard-to-reverse architectural choice without recording why.

★ 0