l3digital-net/ha-quality-review

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

1. Locate integration: custom_components/{domain}/ or homeassistant/components/{domain}/
2. Run automated checks where possible
3. Manual review against checklist
4. 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