# 01 — Design Overview

## 1. Chosen path

**Raise 12 high-popularity, high-issue-volume Home Assistant integrations to an
explicit target tier on the official Quality Scale (Bronze → Silver → Gold, with
Platinum-specific items where cheap), via small, rule-scoped PRs coordinated with
existing code owners.**

This is "generally boring work that provides real quality of life improvement",
exactly as anticipated in the project brief. The Quality Scale gives us something a
freelance contribution effort almost never has: an *official, community-ratified
definition of done*. Home Assistant's architecture decision record **ADR-0007
(Integration Quality Scale)** and the 2024 revamp of the scale (the
`quality_scale.yaml` rule-tracking file in each integration, documented at
developers.home-assistant.io) define ~45 concrete rules across four tiers. Our work
is therefore checkable line-by-line by maintainers and by our backers.

## 2. Why this path (summary of Milestone 1 reasoning)

| Criterion | (A) Bug-fix sweep | (B) Quality-scale uplift | (C) New feature |
|---|---|---|---|
| Durability | Low — fixes land but underlying quality debt persists | **High — each rule closed stays closed; `quality_scale.yaml` tracks it** | Medium — risk of rejection/abandonment |
| Community fit | Medium — competes with triage volunteers | **High — core team actively asks for this; rules are pre-approved** | Low–Medium — needs architecture buy-in |
| Reviewability | Per-fix | **Per-rule, checklisted** | Large, contentious |
| Predictability of effort | Poor (issue quality varies wildly) | **Good (rules are bounded)** | Poor |
| Risk of stepping on maintainers | Medium | **Low if CODEOWNERS coordination is done (see doc 04)** | High |

The decisive point: quality-scale rules like *config-flow test coverage*,
*diagnostics*, *reauthentication flow*, *entity naming via `has_entity_name`*,
*strict typing*, and *availability logging* are precisely the things users feel as
"this integration is flaky / hard to set up / impossible to debug", and they are
precisely the things volunteer maintainers defer because they're tedious. Tedious +
valuable + pre-specified is the ideal shape for funded outside work.

## 3. Goals

1. **G1 — Tier promotions.** Each of the 12 target integrations reaches its
   per-integration target tier (defined in each audit; mostly Silver, several Gold)
   with the tier change accepted into `homeassistant/components/<domain>/manifest.json`
   / `quality_scale.yaml` by the code owners.
2. **G2 — Measurable user-facing wins.** Every integration track must include at
   least two rules with direct user impact (e.g., reauth flow instead of silent
   auth death; diagnostics download for supportability; correct entity naming;
   "log once when unavailable" instead of log spam).
3. **G3 — Test-coverage floor.** Every touched integration ends at ≥ 95% test
   coverage of `config_flow.py` (a Bronze rule) and full-file coverage for any
   module we modify.
4. **G4 — Zero maintainer friction.** No PR opened without the coordination steps
   in doc 04; no PR larger than the sizing conventions in doc 04; zero PRs that
   bypass a code owner's stated preference.
5. **G5 — Auditability.** Every work item in doc 06 maps to (a) a quality-scale
   rule ID, (b) acceptance criteria, (c) eventually a PR URL — so the funding
   ledger maps 1:1 to upstream artifacts.

## 4. Non-goals

- **NG1 — Not rewriting upstream PyPI libraries** except where a Platinum rule
  (`async-dependency`, `inject-websession`) requires a small upstream patch *and*
  the library maintainer is responsive; otherwise the rule is documented as an
  exemption, which the quality-scale format explicitly supports.
- **NG2 — Not adding features** beyond what rules require. Feature requests found
  during audits are filed as issues for code owners, not implemented.
- **NG3 — Not taking over CODEOWNERS slots.** We may *offer* to be added as an
  additional code owner where a maintainer requests it; we never propose it.
- **NG4 — Not touching integrations whose code owner declines.** Reserve targets
  exist for this case (doc 02 §6).
- **NG5 — Not "top 100 to Platinum".** Milestone 1 sized that at 8,000–12,000
  engineer-hours; out of scope for this funding round.

## 5. Scope summary

- **12 primary integrations** (doc 02 §5): `broadlink`, `yeelight`, `denonavr`,
  `onvif`, `dlna_dmr`, `samsungtv`, `transmission`, `androidtv`, `kodi`,
  `harmony`, `fritz`, `nut`.
- **3 reserves** (doc 02 §6): `ping`, `vlc_telnet`, `songpal` — promoted into the
  primary list only if a primary track is blocked by an unresponsive or declining
  code owner.
- **Per integration:** one audit (already delivered in `docs/audits/`), one
  re-verification task, then 4–10 rule-scoped work items per the backlog.
- **Estimated total:** ~95 work items, ~70–90 upstream PRs (some items batch into
  one PR per the sizing rules), executed over Milestones 3–5.

## 6. Phasing (consumed by later milestones)

| Phase | Content | Exit criterion |
|---|---|---|
| P0 | Re-verify all 12 audits against current `dev`; refresh `quality_scale.yaml` deltas; open coordination issues per doc 04 §3 | All 12 coordination threads have code-owner acknowledgment or 14-day silence fallback triggered |
| P1 | Bronze/Silver gap closure for the 6 "fast" tracks (`transmission`, `nut`, `denonavr`, `harmony`, `kodi`, `dlna_dmr`) | Target-tier PRs merged or in review |
| P2 | Bronze/Silver/Gold closure for the 6 "heavy" tracks (`broadlink`, `yeelight`, `onvif`, `samsungtv`, `androidtv`, `fritz`) | Same |
| P3 | Platinum-cheap items (strict typing where near-complete; websession injection where the library supports it); documentation rules on developers/companion docs repos | Backlog burn-down ≥ 90%, remainder documented as exemptions or handed off |

## 7. Risks and mitigations

| # | Risk | Likelihood | Mitigation |
|---|---|---|---|
| R1 | Code owner declines or is unresponsive | Medium (12 tracks → expect 1–3) | Reserve list; 14-day silence protocol in doc 04 §3.4 escalates to opening the PR anyway *only* for rules with zero behavioral change (typing, tests), per HA's normal contribution rules |
| R2 | Audit staleness — another contributor closes a gap first | Medium | P0 re-verification; this is a *good* outcome — we strike the item and the credit returns to backers per ledger rules |
| R3 | A rule requires upstream library changes (e.g., `async-dependency` for a sync library) | High for Platinum items | NG1: small upstream PRs where maintainer responsive; otherwise documented exemption; never fork |
| R4 | Hardware-dependent testing (Broadlink RF, ONVIF cameras, Samsung TVs) | High | All targets chosen to have existing mock/fixture-based test suites; we extend fixtures, never require hardware in CI; doc 05 AC-G7 requires fixture provenance notes |
| R5 | Monthly release churn breaks in-flight PRs | Certain | PR sizing rules (doc 04 §5) keep PRs rebasable in <30 min; one-rule-per-PR default |
| R6 | Review bandwidth of HA core team | Medium | Pace: max 3 concurrently-open PRs per integration, max 10 across the project (doc 04 §5.4) |

## 8. Success metrics

- **M1:** ≥ 10 of 12 integrations reach target tier (merged) by end of Milestone 5.
- **M2:** Tier badges visible on home-assistant.io integration pages (the docs site
  renders `quality_scale` from the manifest).
- **M3:** 90-day post-merge issue-open rate on touched integrations does not
  regress (guardrail metric; quality work must not destabilize).
- **M4:** ≥ 95% config-flow test coverage on all 12 (G3).
- **M5:** Zero PRs closed by maintainers as "unwanted/out of process" (G4).

## 9. Out-of-scope follow-ups identified (for future funding rounds)

- A reusable **quality-scale gap scanner** (static analysis of
  `quality_scale.yaml` `todo`/`exempt` entries + heuristics for unmarked legacy
  integrations) — prototyped during Milestone 1 analysis; productizing it is a
  natural Milestone 6 candidate and would benefit the whole community.
- The remaining ~85 of the "top 100" integrations.