Home Assistant Integration Quality Scale Review

Run with /home-assistant-dev:ha-quality-review to perform a systematic review against all official IQS rules.

Overview

The Integration Quality Scale has 4 tiers and 52 rules:

Bronze (18 rules): Minimum for new core integrations
Silver (10 rules): Reliability and maintainability
Gold (21 rules): Best user experience
Platinum (3 rules): Technical excellence

Review Process

Locate integration: custom_components/{domain}/ or homeassistant/components/{domain}/
Run automated checks where possible
Manual review against checklist
Generate report with findings

Bronze Tier (18 Rules) — Required for Core

Code Organization

[ ] action-setup: Service actions registered in async_setup, not async_setup_entry
[ ] common-modules: Common patterns in dedicated modules (coordinator.py, entity.py)
[ ] dependency-transparency: All dependencies listed in manifest.json requirements
[ ] runtime-data: Uses entry.runtime_data not hass.data[DOMAIN]

Config Flow

[ ] config-flow: Setup via UI with config_flow: true in manifest
- Uses data_description in strings.json for field context
- ConfigEntry.data for connection info, ConfigEntry.options for settings
[ ] config-flow-test-coverage: Full test coverage for config flow
[ ] test-before-configure: Validates connection during config flow
[ ] unique-config-entry: Prevents duplicate config entries via async_set_unique_id

Entities

[ ] entity-unique-id: Every entity has stable unique_id
[ ] has-entity-name: All entities use _attr_has_entity_name = True
[ ] entity-event-setup: Event subscriptions in async_added_to_hass, cleanup in async_will_remove_from_hass

Setup & Reliability

[ ] test-before-setup: Validates connection in async_setup_entry, raises ConfigEntryNotReady on failure
[ ] appropriate-polling: Reasonable polling interval (not too frequent)

Documentation & Branding

[ ] brands: Has logo/icon in home-assistant/brands
[ ] docs-high-level-description: Documentation describes what the integration does
[ ] docs-installation-instructions: Step-by-step setup instructions
[ ] docs-removal-instructions: How to remove the integration
[ ] docs-actions: Documents all service actions

Silver Tier (10 Rules) — Reliability

Error Handling

[ ] action-exceptions: Service actions raise ServiceValidationError or HomeAssistantError on failure
[ ] entity-unavailable: Entities marked unavailable when device/service unreachable
[ ] log-when-unavailable: Logs once when unavailable, once when reconnected (DataUpdateCoordinator handles this)

Lifecycle

[ ] config-entry-unloading: Implements async_unload_entry properly
[ ] reauthentication-flow: Implements async_step_reauth for credential refresh

Performance

[ ] parallel-updates: Sets PARALLEL_UPDATES constant to limit concurrent entity updates

Maintenance

[ ] integration-owner: Has active codeowner in manifest.json
[ ] test-coverage: ≥95% test coverage

Documentation

[ ] docs-configuration-parameters: Documents all options flow parameters
[ ] docs-installation-parameters: Documents all config flow parameters

Gold Tier (21 Rules) — Best Experience

Devices & Entities

[ ] devices: Creates device entries with DeviceInfo
[ ] entity-category: Uses EntityCategory.CONFIG or EntityCategory.DIAGNOSTIC appropriately
[ ] entity-device-class: Uses appropriate device classes
[ ] entity-disabled-by-default: Disables noisy/rarely-used entities by default
[ ] entity-translations: Entity names use translation_key
[ ] dynamic-devices: Handles devices appearing/disappearing after setup
[ ] stale-devices: Removes devices that are no longer present

Discovery

[ ] discovery: Supports Zeroconf/SSDP/DHCP/USB/Bluetooth discovery
[ ] discovery-update-info: Updates device network info from discovery

Advanced Flows

[ ] reconfiguration-flow: Implements async_step_reconfigure for changing settings
[ ] repair-issues: Uses repair registry for actionable user notifications

Diagnostics

[ ] diagnostics: Implements diagnostics.py with sensitive data redaction

Translations

[ ] exception-translations: Exception messages are translatable
[ ] icon-translations: Uses icon translations in icons.json

Documentation

[ ] docs-data-update: Documents polling interval and update method
[ ] docs-examples: Provides automation examples
[ ] docs-known-limitations: Documents limitations
[ ] docs-supported-devices: Lists supported devices/models
[ ] docs-supported-functions: Documents supported features
[ ] docs-troubleshooting: Provides troubleshooting guide
[ ] docs-use-cases: Shows example use cases

Platinum Tier (3 Rules) — Excellence

[ ] async-dependency: Third-party library is fully async (no executor wrapping needed)
[ ] inject-websession: Library accepts Home Assistant's aiohttp session
[ ] strict-typing: Full type annotations, passes mypy --strict

Quick Validation Commands

# Validate JSON files
python3 -c "import json; json.load(open('manifest.json'))"
python3 -c "import json; json.load(open('strings.json'))"

# Check for common issues
grep -r "hass.data\[DOMAIN\]" .  # Should use runtime_data
grep -r "requests\." .           # Should use aiohttp
grep -r "time.sleep" .           # Should use asyncio.sleep

# Run linters
ruff check .
mypy .

Output Format

## Integration Quality Review: {domain}

### Tier Assessment
- Bronze: {X}/18 ✓/✗
- Silver: {X}/10 ✓/✗
- Gold: {X}/21 ✓/✗
- Platinum: {X}/3 ✓/✗

**Current Tier:** {highest fully passing tier}

### Critical Issues (Must Fix for Bronze)
1. [Rule]: [Issue] — [File:line]
   Fix: [code example]

### Warnings (Should Fix)
1. [Rule]: [Issue]

### Recommendations for Next Tier
1. [Prioritized improvements]

### Positive Findings
- [What's done well]

Related Skills

Config flow issues → ha-config-flow
Coordinator issues → ha-coordinator
Entity issues → ha-entity-platforms
Async issues → ha-async-patterns
Diagnostics → ha-diagnostics
HACS compliance → ha-hacs