what_to_wear/docs/superpowers/specs/2026-07-11-what-to-wear-design.md

What to Wear (WTW) — Design-Spec v1

• Datum: 2026-07-11
• Status: Entwurf zur Review (Brainstorming-Ergebnis; Keim für den BMAD-PRD)
• Methode: AI-Dev-Method (BMAD + adversariale Reviewer-Linsen + KI-Zweitkritiker)
• Domain / Name: what_to_wear — „What to Wear (WTW)"

---

1. Intent (ein Satz)

Eine quelloffene Home-Assistant-Integration, die dem Nutzer abends sagt, welche konkreten Kleidungsstücke aus seinem Kleiderschrank er für morgen rauslegen soll — deterministisch aus der Wetterprognose abgeleitet, optional sprachlich schön formuliert, ausgespielt über Dashboard / Push / Ansage.

2. Problem & Zielgruppe

• Problem: Morgens Zeitdruck und Fehlgriffe bei der Kleidung; abends fehlt der schnelle Überblick, was das Wetter morgen konkret verlangt (Regen, Frost, Wind, UV) — und was davon man überhaupt besitzt.
• Zielgruppe: Home-Assistant-Nutzer (DACH + international), die abends Kleidung vorbereiten — Pendler, Eltern (Kind anziehen), Menschen mit festem Morgenritual.
• Vertriebskontext: Open-Source-HACS-Produkt (Reichweite/Reputation), später Upsell über einen optionalen LagerLens-Connector (KI-Foto-Katalogisierung der Kleidung).

3. Umfang v1 — bewusste Nicht-Ziele (v1.1+)

In v1:

• HACS-Custom-Integration what_to_wear, Config-Flow, Options-Flow.
• Kleiderschrank-Inventar nativ über HA-Sub-Entries (echte Stücke mit Eigenschaften).
• WeatherProvider-Interface mit einer Implementierung: HA-Wetter-Entität.
• Pipeline: Normalizer → Regel-Engine → Matcher → (optional) LLM-Ton.
• Ausgabe: Empfehlungs-Sensor + Service/Event; read-only Lovelace-Karte; 2 Blueprints (Push, TTS).
• Optionaler LLM-Ton (Bring-your-own-Key, default AUS).
• i18n de + en.

Bewusst vertagt (v1.1+):

• LagerLens-Connector als zweite Kleiderschrank-Quelle.
• Open-Meteo als zweiter WeatherProvider.
• Schöne CRUD-Verwaltungskarte für den Kleiderschrank (v1: native HA-UI genügt).
• Mehrere Personen/Profile; Aktivitäts-/Kalenderkontext (Termine, „heute Sport"); Wäsche-/Verfügbarkeitsstatus.

4. Produktform & Distribution

• Standard-HA-custom_component (Python, async), HACS-installierbar; MVP-Struktur:

  custom_components/what_to_wear/   __init__.py, manifest.json, config_flow.py, coordinator.py,
                                    sensor.py, services.yaml, strings.json, translations/{de,en}.json,
                                    weather/ (provider-interface + ha_entity impl),
                                    logic/ (normalize.py, rules.py, matcher.py, phraser.py)
  blueprints/automation/what_to_wear/  notify_push.yaml, announce_tts.yaml
  www/what-to-wear-card.js             (read-only Lovelace-Karte)
  

• Lizenz: Vorschlag MIT (offene Kleinentscheidung).
• Min-HA-Version: Vorschlag 2024.12+ (für weather.get_forecasts mit return_response=True und Config-Sub-Entries) — in der Architektur-Phase gegen die tatsächlich benötigten APIs verifizieren.
• Repo: lokal (git master), Remote später.

5. Architektur — Pipeline & Komponenten

WeatherProvider ─▶ ForecastNormalizer ─▶ RulesEngine ─▶ WardrobeMatcher ─▶ (opt.) LLMPhraser
                                                                                    │
                          RecommendationSensor  ◀───────────────────────────────────┘
                                   │
                 (User-Automation via Blueprint) ─▶ Push / TTS / Lovelace-Karte

• WeatherProvider (Interface async get_tomorrow_forecast() -> RawForecast): v1-Impl liest die vom Nutzer gewählte weather.*-Entität via weather.get_forecasts (daily + hourly, return_response=True).
• ForecastNormalizer: RawForecast → NormalizedForecast für morgen (lokale TZ), interne SI-Einheiten, je Feld ein „vorhanden?"-Flag. Aggregiert stündlich → Tageswerte nach lokalem Datum.
• RulesEngine: NormalizedForecast → Liste Requirement (Eigenschaft + Grund + Priorität).
• WardrobeMatcher: Requirements × Kleiderschrank → gewählte Stücke + Begründung + Lücken („keine Regenjacke").
• LLMPhraser (optional): formt nur den Text; bei Aus/Fehler → deterministischer Regeltext.
• DataUpdateCoordinator: hält das morgige Ergebnis aktuell; Benachrichtigung triggert der Nutzer per Blueprint.

Invarianten-Spine (Keim für die Architektur-Phase)

• INV-1 (Nie stumm): Die Empfehlung fällt nie aus. Bei Teil-Ausfall (LLM, fehlendes Wetterfeld, leerer Schrank) liefert der deterministische Kern trotzdem eine Empfehlung und benennt die Lücke.
• INV-2 (Morgen lokal): „Morgen" ist stets das lokale Kalenderdatum in hass.config.time_zone (DST-fest).
• INV-3 (SI intern): Interne Berechnung nur im SI-Normmodell; Quelle/Einheit/Missingness bleiben am Datum erhalten; Werte werden nie aus Feldname oder Größenordnung geraten.
• INV-4 (Geheimnisse): LLM-Key (später LagerLens-Token) nie im Klartext in Logs/State/Attributen; nur im HA-Config-Storage.
• INV-5 (Keine stille Netzlast): v1 spricht nur mit HA selbst. Externe Provider (v1.1) nur opt-in, mit Coordinator/Timeout/Backoff/Attribution; kein stiller Provider-Wechsel.
• INV-6 (Trennung): Normalize / Rules / Matcher sind strikt getrennt und je einzeln testbar.

6. Datenmodell

• Kleidungsstück (Sub-Entry): name, kategorie (z. B. Jacke/Pullover/Hose/Schuhe/Accessoire/Kopf/Hand), waerme 1–5, wasserdicht bool, winddicht bool, formalitaet (leger/business), saison/Temp-Range (optional), foto (optional), aktiv bool.
• NormalizedForecast (morgen): temp_min, temp_max, temp_gefuehlt_min/max (°C), regen_wkt (%), regen_menge (mm), wind / boeen (km/h), uv_index, zustand (klar/bewölkt/Regen/Schnee/Gewitter) — jeweils mit vorhanden-Flag + Herkunft/Zeitstempel.
• Requirement: eigenschaft (z. B. wasserdichte_aussenschicht, waerme_min:4, sonnenschutz, handschuhe, muetze), grund (menschlesbar), prioritaet (muss/soll/kann).
• Recommendation: kurztext (Sensor-State), stuecke[], requirements[], luecken[], kennwerte, quelle.

7. Regel-Engine (illustrative Schwellwerte — final in PRD/Architektur)

Beispielhaft, konfigurierbar; nicht endgültig. Kälteempfinden-Offset verschiebt Temperaturschwellen.

• temp_gefuehlt_max < 0 °C → waerme_min:5, muetze, handschuhe, schal.
• 0–8 °C → waerme_min:4; 8–15 °C → waerme_min:3; 15–22 °C → waerme_min:2; > 22 °C → waerme_min:1, ggf. sonnenschutz.
• regen_wkt ≥ 40 % oder regen_menge ≥ 1 mm → wasserdichte_aussenschicht, feste_schuhe.
• boeen ≥ 40 km/h → winddicht.
• uv_index ≥ 6 → sonnenschutz (Brille/Kopfbedeckung).
• zustand = Schnee → waerme_min:4, wasserdicht, profilsohle.

8. Matcher

• Wählt je Requirement das am besten passende aktive Stück (Priorität muss > soll > kann; bei Gleichstand nächstpassende Wärme/Formalität).
• Fehlt ein Stück für ein muss/soll-Requirement → Lücke in luecken[] (z. B. „Für morgen wäre eine Regenjacke ideal — keine im Schrank hinterlegt.").
• Ergebnis ist erklärbar: jedes Stück trägt seinen Grund (welches Requirement es erfüllt).

9. LLM-Ton (optional, Bring-your-own-Key)

• Default AUS. Nutzer trägt eigenen Key (OpenAI/Anthropic) im Options-Flow ein → nur im Config-Storage.
• Eingabe an das LLM: die strukturierte Recommendation (Stücke + Gründe + Kennwerte) + Zielsprache. Aufgabe: nur umformulieren, keine neuen Fakten, keine geänderte Stückauswahl.
• Fehler/Timeout/kein Key → deterministischer Regeltext (INV-1). LLM ändert nie die Auswahl.

10. Ausgabe: Sensor / Service / Karte / Blueprints

• Sensor sensor.what_to_wear: state = Kurzempfehlung; attributes = stuecke, requirements, luecken, kennwerte, quelle, stand.
• Service/Event what_to_wear.recommend (manuelles Neuberechnen; feuert Event mit dem Ergebnis).
• Lovelace-Karte (read-only): zeigt morgige Empfehlung + Stücke + Lücken dauerhaft.
• Blueprints: notify_push (Nutzer wählt notify-Ziel + Uhrzeit), announce_tts (Nutzer wählt media_player + Auslöser). Import ist ein geführter HA-Klick-Flow → laienfreundlich, ohne notify-Logik in der Integration.

11. Konfiguration

• Config-Flow (Ersteinrichtung): Wetter-Entität wählen (Entity-Selector, Pflicht; Fehler wenn keine da), Sprache (Default = HA-Sprache), Kälteempfinden-Offset.
• Options-Flow: Schwellwerte/Offsets, optionaler LLM-Key + Provider (default aus).
• Sub-Entries: Kleidungsstücke anlegen/bearbeiten/löschen in der nativen HA-UI.

12. Fehlerbehandlung & Edge Cases (aus dem Kritiker-Review)

• Keine geeignete weather.*-Entität → klarer Config-Fehler, kein Raten (INV-1/Config).
• Wetterfeld fehlt → Regel greift degradiert + Hinweis; „fehlend" ≠ „0" (INV-3).
• „Morgen"/DST strikt in lokaler TZ (INV-2).
• LLM-Fehler/Timeout/kein Key → Fallback auf Regeltext (INV-1).
• Leerer/lückenhafter Schrank → Anforderung + Lücke nennen statt schweigen (INV-1).
• Einheiten (°C/°F, km/h/mph, mm/inch) bewusst konvertieren; Open-Meteo-Wettercode ↔ HA-condition per Mapping-Tabelle (v1.1).

13. i18n

• HA-Translations für UI (de, en); Empfehlungstext folgt der HA-Sprache; Regeltext-Bausteine je Sprache.

14. Tests & echte Verifikation (Methoden-Pflicht)

• Unit: Normalizer/Rules/Matcher mit Wetter-Fixtures (Regen, Frost, Hitze, DST-Tag, fehlende Felder, leerer Schrank).
• Integration: pytest-homeassistant-custom-component (Config-Flow, Sensor, Service).
• Echte E2E: Wegwerf-HA-Docker-Instanz — Integration installieren → Wetter-Entität + Beispielschrank → Sensor prüfen → Blueprint-Push real auslösen. Negativfälle (keine Wetter-Entität, LLM-Key falsch).
• TDD: Test rot → Code → grün → volle Suite → Commit (ein Commit pro Story). qwen/Cloud-Review nach jeder Story.

15. Offene Punkte / Annahmen (in PRD/Architektur klären)

• Lizenz (Vorschlag MIT). Min-HA-Version (Vorschlag 2024.12+, gegen APIs verifizieren).
• Ob v1 die Sub-Entry-CRUD-UX von HA praktisch trägt (sonst früher CRUD-Karte).
• Genaue Schwellwerte/Regeln (Kap. 7 illustrativ).
• Foto-Speicherung bei nativem Kleiderschrank (Pfad/Umfang) — v1 optional/minimal.

16. Roadmap v1.1+

LagerLens-Connector (Foto-Katalog) · Open-Meteo-Provider · CRUD-Verwaltungskarte · Mehrpersonen-Profile · Aktivitäts-/Kalenderkontext · Wäsche-/Verfügbarkeitsstatus.