# 07 — Recommendation & Risk Register

## 07.1 Recommendation

**Adopt a hybrid program: a Baseline Quality-Scale Uplift Wave (P3) as the spine, with
triage-driven bug fixing (P1) interleaved on the same integrations, accelerated by a short
upfront developer-tooling investment (P6).**

Explicitly **declined**: Platinum-100 uplift (P2) and unsolicited user-facing features (P4).
Both scored last under every sensitivity perturbation (report 06 §06.5), for structural
reasons — effort blowup via upstream-library obligations, and architecture-review stall risk
on core-owned surfaces — not for lack of value in the abstract.

### Why this hybrid

1. **It is the work the project has asked for.** The quality pillar is the one roadmap area
   where the core team built machinery and explicitly delegated the labor to the community
   (report 05 §05.3). Alignment converts directly into merge probability.
2. **The two top absolute-impact paths reinforce each other.** Uplifting an integration to
   Silver (reauth, availability, logging hygiene, config-flow tests) *prevents* the dominant
   issue classes found in the report 04 triage; fixing that integration's open bugs while in
   the codebase amortizes context-loading cost — the single largest hidden cost in
   integration work.
3. **Tooling-first lowers marginal cost across the whole wave.** A quality-scale auditor
   (machine-checkable subset of the rules) and two codemods (`hass.data`→`runtime_data`,
   entity-naming migration) turn repeated manual audits into minutes of work, and remain
   useful to every other community contributor even if never upstreamed (sensitivity test #2).

### Program shape

| Phase | Duration | Content | Exit criteria |
|-------|----------|---------|---------------|
| **0 — Tooling** | 2–3 weeks | Out-of-tree quality-scale auditor; codemods for the two highest-frequency migrations; wave target selection | Auditor validated against ≥10 integrations of known tier; targets list signed off |
| **1 — Pilot wave** | 4–6 weeks | 5 integrations from the target list (mixed: 2 with active code owners, 2 ownerless, 1 YAML-legacy), full Bronze→Silver uplift + open-bug burn-down on each | ≥4 of 5 fully merged; review-latency and effort-per-rule actuals captured |
| **2 — Main wave** | ongoing, quarterly checkpoints | Remaining ~40–55 targets, sequenced by install base × auditor-measured rule gap; P1 fixes interleaved | Per-quarter: integrations uplifted, issues closed, regression count |
| **2b — Opportunistic upstreaming** | parallel | Offer auditor/codemods to core tooling (scaffold, hassfest) if reception is positive | Optional; not a success dependency |

### Target selection rule (Phase 0 output)

From `data/top_integrations.csv` ∩ `data/quality_scale_distribution.csv`, select integrations
where: install-base rank ≤ 150, current tier ∈ {legacy/no-score, Bronze}, no open architecture
dispute, upstream library released within 18 months (proxy for maintainability), and either a
responsive code owner (commit/review activity ≤ 90 days) or no code owner. The triage data
(`data/issue_triage.csv`) supplies each target's bug burn-down list.

### Success metrics

- **Primary:** integrations raised at least one full tier with merged, rule-referenced PRs;
  analytics-weighted install coverage of uplifted set.
- **Secondary:** open issues closed-by-fix in target integrations; reduction in *new* issue
  inflow rate for uplifted integrations over the following two release cycles (the Silver-tier
  prevention hypothesis, measurable from the issue tracker).
- **Guardrails:** zero net-new regressions attributable to uplift PRs (tracked via issue
  bisection); abandoned-PR rate < 15%.

---

## 07.2 Risk register

| ID | Risk | L | I | Exposure | Mitigation | Trigger / early signal |
|----|------|---|---|----------|------------|------------------------|
| R1 | **Review-bandwidth bottleneck** — PRs queue for weeks, throughput collapses | M | H | High | Rule-scoped small PRs (the format reviewers requested); pilot phase measures real latency before scaling; batch independent integrations to keep pipeline full | Median time-to-first-review > 14 days in pilot |
| R2 | **Code-owner absenteeism** on target integrations stalls merges | M | M | Med | Target-selection rule prefers responsive or absent (core-reviewed) owners; drop-and-replace targets rather than waiting | Two pings unanswered in 14 days |
| R3 | **Upstream library blockage** — Silver rule needs a library change; library unmaintained | M | M | Med | Pre-screen library release recency in selection; where blocked, deliver partial tier with documented exemption per scale rules; small upstream PRs acceptable, library adoption is not | Auditor flags library-coupled rule gap |
| R4 | **Quality-scale rules churn** — core revises rule definitions mid-wave | L | M | Low | Rules are versioned in core docs; auditor reads rule definitions from a pinned core ref, re-pin per quarter | Developer-blog rule-change post |
| R5 | **Regression introduced by uplift** damages trust and future merge probability | L | H | Med | Config-flow + behavioral tests in every PR (also a tier requirement); avoid drive-by refactors outside the rule's scope; guardrail metric with stop-the-line rule | Any bisected regression report |
| R6 | **Duplicate/conflicting work** — code owner or core was already uplifting the target | L | L | Low | Check open PRs and recent commits during selection; comment intent on the integration's tracking issue before starting | Open uplift PR found |
| R7 | **Social friction** — wave perceived as scoreboard-chasing or review-load dumping | L | H | Med | Pilot deliberately small; communicate plan in the community forum/Discord dev channel before the main wave; prioritize issue-closing alongside tier-climbing so value is legible | Negative reviewer feedback in pilot |
| R8 | **Tooling sunk cost** — auditor/codemods take longer than the work they save | L | M | Low | Hard 3-week timebox on Phase 0; auditor covers only machine-checkable rules (~60% of Bronze/Silver), no attempt at full automation | Phase 0 overrun |
| R9 | **CI flakiness / core churn** breaks open PRs repeatedly | M | L | Low | Rebase cadence; keep PRs small so rebases are cheap | >2 forced rebases per PR |
| R10 | **Analytics bias in targeting** — opt-in analytics undercounts privacy-conscious deployments (report 01 caveat) | M | L | Low | Selection uses install rank as one input among several; sanity-check targets against issue volume and forum activity | — |
| R11 | **Scope creep toward Platinum** — "while we're here" async/typing rewrites inflate diffs | M | M | Med | Tier ceiling per wave: stop at Silver (Gold only where docs/test gap is trivial); reviewer-visible checklist defines done | PR diff > ~600 lines |

L/I = likelihood/impact (L/M/H). Exposure = qualitative product, drives mitigation priority.

---

## 07.3 Decision summary

The analysis (reports 02–06) converges from three independent directions — quality-scale
distribution (bottom-heavy catalog), issue triage (preventable issue classes dominate), and
roadmap signals (community labor explicitly invited on exactly this surface) — on the same
answer. The hybrid P3+P1 program with a P6 head start is the recommended contribution path,
with the pilot wave as a cheap falsification test: if review latency or social reception
invalidates the model's merge-probability assumptions, the program de-scopes to pure P1 bug
fixing (the rank-3 path, viable standalone) at negligible sunk cost.