# Executive Summary

## The question

Home Assistant has one of the healthiest contributor communities in open source: ~20k merged
PRs per year on `home-assistant/core` alone, a paid core team funded by Nabu Casa and (since
2024) governed by the Open Home Foundation, and an explicit public roadmap. The question for
an outside, well-funded contributor is therefore **not** "what does the project need that
nobody is doing?" but "**where is the marginal contributor-hour worth the most, without
colliding with the core team's lane?**"

## What the analysis found

Three structural facts dominate the answer:

1. **The integration layer is where the quality variance lives.** Home Assistant Core's
   kernel (event bus, state machine, entity model, config entries, recorder) is mature,
   strictly typed, and well-tested. The ~2,800 bundled integrations are not. The project
   formalized this in October 2024 by relaunching the **Integration Quality Scale**
   (Bronze → Silver → Gold → Platinum) with machine-checkable rules per tier. As of the
   snapshot in this report, **fewer than ~2% of integrations are Platinum, only a small
   single-digit percentage sit at Gold or above, and the overwhelming majority — including
   dozens of integrations installed on more than 10% of all reporting installations — carry
   no tier at all or sit at Bronze/legacy.** The core team has explicitly said they want the
   community to drive tier uplift; they built the rule framework precisely so outsiders can.

2. **Open issues cluster, they don't spread.** Of the ~2,300–2,600 open issues typically
   carried on `home-assistant/core`, the top ~150 integrations by install base account for a
   clear majority, and within those, a handful of recurring themes account for most reports:
   broken reauthentication after cloud-token expiry, missing/incorrect device classes and
   units, connection-recovery failures (integration requires a restart after a device or
   cloud blip), and upstream API drift in the pinned client library. These are exactly the
   failure classes the Quality Scale's Silver tier rules exist to prevent
   (`reauthentication-flow`, `test-coverage`, `entity-unavailable`, `log-when-unavailable`,
   `parallel-updates`). **Bug clusters and quality-scale gaps are the same problem viewed
   from two sides.**

3. **The core team's roadmap deliberately does not cover this.** The published roadmap
   concentrates the paid team on voice/Assist, AI integration, local-first device
   connectivity (Matter/Thread/Zigbee/Z-Wave infrastructure), dashboard/UX, and the Open
   Home Foundation's privacy/data-ownership agenda. Integration-level polish is explicitly
   delegated to the community and to per-integration code owners — many of whom are inactive.

## The ranked paths (full scoring in report 06)

| Rank | Path | Impact/Effort score | One-line verdict |
|---|---|---|---|
| **1** | **Quality-scale uplift of the top ~50 high-install integrations (Bronze→Silver, Silver→Gold), with triage-driven bug fixing folded in** | **8.1** | Highest leverage; aligned with explicit core-team intent; merge-friendly; compounding (tests + rules prevent regressions) |
| 2 | Bulk bug fixing across the top 150 integrations (issue-down approach) | 6.3 | Real value but lower durability; many fixes need the same scaffolding (tests, reauth flows) the uplift path builds anyway |
| 3 | "Polish the top 100 to Platinum" | 4.9 | Platinum requires full async client libraries + strict typing end-to-end; effort explodes on integrations with synchronous third-party libs the contributor doesn't control |
| 4 | Feature-gap implementation (best candidate identified: first-class integration health/diagnostics dashboard) | 4.2 | Genuinely valuable but requires architecture sign-off, frontend work, and core-team bandwidth to review; high rejection risk for an outsider |
| 5 | New-language rewrite / library replacement programs | 1.1 | Rejected; effort catastrophic, community cost severe |

## The recommendation

**Run a structured Quality-Scale Uplift Program targeting the top ~50 integrations by
install base that sit below Silver, bringing each to Silver (and to Gold where the
integration's device model supports it), and fixing the open-issue backlog of each
integration as part of its uplift.**

Concretely, per integration: full config-flow and reauth/reconfigure flows, >95% test
coverage of the integration's setup and flows, `DataUpdateCoordinator`-based update logic
with correct unavailability handling, diagnostics, proper device/entity naming and
translations, and closure or reproduction-triage of its open issues. This is "boring" work
by design — and it is precisely the boring work the project has built scaffolding to receive,
that code owners are not doing, and that materially improves daily life for the largest
number of users per engineering hour. Reports 03–06 substantiate each claim above with data;
report 07 scopes the follow-on milestones.