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
- 参考文档references/core-lint-checks.md15.8 KB
- 参考文档references/quality-scale-rules.md21.3 KB
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/). Ahelpers/,common/,shared/, orlib/package is a finding. - Files are 200–400 lines, one entity class per file.
- Runtime state lives in
entry.runtime_data, neverhass.data[DOMAIN]. - No circular imports;
TYPE_CHECKINGguards 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 inentity.pyand actions inservices.py. This project'scoordinator/,entity/andservice_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 inasync_setup(), not per entry.parallel-updates— every platform package's__init__.pydefinesPARALLEL_UPDATESat module level:0on a read-only coordinator platform, a value the device can take on platforms that send commands.entity-translations/icon-translations— no hardcodedname=oricon=inEntityDescription.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,
-> Noneon procedures, no bareAnywhere aTypedDictor dataclass is meant, nofrom __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.timeoutrather than a deprecated helper. - Exceptions — specific types, never bare
except:;raise ... from errto preserve the chain; the coordinator translates client exceptions intoUpdateFailed/ConfigEntryAuthFailedcorrectly. - Properties — no I/O, no raising, no side effects.
- Constants — no magic numbers or duplicated strings; reuse
homeassistant.constnames. - Logging — lazy
%sformatting,debugfor 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)orint(value)on something that can beNoneor a string:bool(None)turns a missing value into "off", andbool("0")isTrue. Convert explicitly (value == "1"). entry.runtime_dataread where setup may have failed — error paths, unload, and anything iteratingasync_entries(). It is set only for a loaded entry; useasync_loaded_entries()and handle none.- Lifecycle boundaries — every listener, timer and connection opened in setup or
async_added_to_hassis released throughentry.async_on_unload/self.async_on_remove, and connections also close on Home Assistant stop. Atrythat wraps everything is not a fix; smalltryblocks 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 forconfig-flow—blueprint.config_flow. - Diagnostics redact the whole payload, and
TO_REDACTstill matches the API response —blueprint.diagnostics. - TLS verification on by default; a
CONF_VERIFY_SSLoption defaults toTrue, 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.jsonandrequirements.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 throughha-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_registerthat callsregister.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 asystem_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: correctintegration_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-marketplacehas 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
issues
Triage/fix the GitHub issue backlog via branch + PR, with auto-merge on green CI for this session.
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`.
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.
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.
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.
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.