# FablePool × Home Assistant — Milestone 2: Contribution Strategy & Design Document

This repository contains the complete design document for our funded Home Assistant
contribution effort. Milestone 1 (Ecosystem Analysis & Impact Assessment) concluded
that the highest impact-per-effort path is **systematically raising a curated set of
popular, high-issue-volume integrations up the official Home Assistant Quality Scale**,
rather than a new feature or a rewrite. Milestone 2 turns that conclusion into an
executable plan.

## Document map

| Path | Contents |
|---|---|
| `docs/01-design-overview.md` | Chosen path, goals/non-goals, scope, risks, success metrics, phasing |
| `docs/02-selection-methodology.md` | Scoring model, data sources, and the selected target list (12 primary + 3 reserve integrations) |
| `docs/03-quality-scale-audit-rubric.md` | The audit rubric mapped to the official HA Quality Scale rules; evidence standards used in every audit |
| `docs/audits/<integration>.md` | Per-integration gap audits (one file per target integration) |
| `docs/04-community-engagement-plan.md` | Maintainer-ownership-respecting engagement plan: ADR alignment, CODEOWNERS coordination, PR sizing, review etiquette |
| `docs/05-acceptance-criteria.md` | Global acceptance criteria: the definition-of-done rules every work item must satisfy |
| `docs/06-work-item-backlog.md` | The full enumerated backlog: every work item, per integration, with per-item acceptance criteria, size, and sequencing |

## How to read this document set

1. Start with `01-design-overview.md` for the strategy and its rationale.
2. `02-selection-methodology.md` justifies *which* integrations we touch and why.
3. Each file in `docs/audits/` is a self-contained gap analysis for one integration,
   structured identically (per the rubric in `03`), so reviewers can diff integrations
   against each other.
4. `04` and `05/06` are the operational half: how we work *with* the existing
   community, and how anyone (backers, maintainers, our own engineers) can verify
   that a work item is genuinely done.

## Important caveat on audit freshness

Home Assistant ships a new core release every month and integration code moves fast.
Every audit in `docs/audits/` is a **snapshot taken against Home Assistant Core
2025.6.x and the `dev` branch as analyzed during Milestone 1**. Each audit therefore
carries a mandatory **"Re-verification before work starts"** section, and the backlog
in `06` makes re-verification the first work item of every integration track. No PR
is to be opened from a stale audit.

## Relationship to Milestone 1

Milestone 1 evaluated three candidate paths from the original brief:

- (A) broad low-hanging bug fixing across many integrations,
- (B) polishing top integrations toward Platinum on the Quality Scale,
- (C) a self-identified major feature gap.

It scored (B) highest on durability of impact (quality-scale work is checklisted,
reviewable, and doesn't bit-rot the way drive-by bug fixes do), community fit
(the core team explicitly created the Quality Scale program and tracks tier
progress per integration), and effort predictability. This milestone designs path
(B), with a deliberately bounded scope: **12 integrations to a defined target tier
each**, not "top 100 to Platinum", which Milestone 1 sized as multi-year work.