mitai-jinkendo/.claude/docs/audit/platzhalter/audit-report-2026-03-29/04_OFFENE_ENTSCHEIDUNGEN.md

# Offene Entscheidungen: Placeholder-Audit

**Audit-Datum:** 29. März 2026
**Status:** Pending Product/Tech Review
**Entscheidungsträger:** Product Manager + Tech Lead

---

## ENTSCHEIDUNGSPFLICHTIGE PUNKTE

Diese Punkte können nicht rein aus Code und Fachlogik gelöst werden und benötigen eine **Produkt-/Fachentscheidung**.

---

## KATEGORIE 1: Zeitfenster-Klassifizierung (BLOCKING P0)

### E1.1: Scores - Zeitfenster definieren

**Betroffene Platzhalter:** 6
- `activity_score`
- `nutrition_score`
- `recovery_score`
- `body_progress_score`
- `goal_progress_score`
- `data_quality_score`

**Problem:**
Scores kombinieren verschiedene Zeitfenster-Metriken. Welches Zeitfenster soll dokumentiert werden?

**Optionen:**

| Option | Beschreibung | Pro | Contra |
|--------|--------------|-----|--------|
| **A: `custom`** | Scores haben keinen festen Zeitrahmen | Technisch korrekt | Unspezifisch für User |
| **B: `mixed`** | Scores kombinieren verschiedene Zeitfenster explizit | Kommuniziert Komplexität | Ähnlich unklar wie `custom` |
| **C: Dominantes Zeitfenster** | Z.B. `28d` für nutrition_score (da Hauptkomponenten 28d) | Einfach zu verstehen | Vereinfachung, evtl. irreführend |
| **D: Zeitfenster pro Sub-Score dokumentieren** | Semantic Contract listet alle Sub-Zeitfenster | Vollständig transparent | Komplex für einfache Use-Cases |

**Empfehlung Audit-Agent:**
- **Option D** für `semantic_contract` (vollständige Transparenz)
- **Option B** für `time_window` Metadatum (signalisiert Komplexität)

**Beispiel (nutrition_score):**
```json
{
  "key": "nutrition_score",
  "time_window": "mixed",
  "semantic_contract": "Composite Score aus: energy_balance (7d), protein_adequacy (28d), macro_consistency (28d). Gewichtung: 40%/40%/20%"
}
```

**Entscheidung benötigt bis:** P0 Week 1 (Zeitfenster-Klassifizierung)
**Impact:** MEDIUM (betrifft Prompt-Interpretation)
**Entscheider:** Product Manager

---

### E1.2: Ability Balance - Zeitfenster definieren

**Betroffene Platzhalter:** 5
- `ability_balance_coordination`
- `ability_balance_endurance`
- `ability_balance_mental`
- `ability_balance_mobility`
- `ability_balance_strength`

**Problem:**
Code implementiert noch keine Ability Balance-Berechnung. Welches Zeitfenster ist fachlich sinnvoll?

**Optionen:**

| Option | Beschreibung | Pro | Contra |
|--------|--------------|-----|--------|
| **A: `28d`** | Rolling-Window über 28 Tage | Konsistent mit anderen Trend-Metriken | Evtl. zu lang für Balance-Shifts |
| **B: `14d`** | Rolling-Window über 14 Tage | Schnellere Reaktion auf Training-Changes | Weniger stabil bei Lücken |
| **C: `latest`** | Snapshot der aktuellen Balance | Einfach | Keine Trend-Info |

**Empfehlung Audit-Agent:**
- **Option A (`28d`)** - Konsistent mit body_metrics, ausreichend stabil

**Rationale:**
- Ability Balance = Verteilung der Trainings-Last über Fähigkeiten
- 28 Tage = ~4 Wochen = typischer Mikrozyklus
- Matching mit anderen Tracking-Metriken

**Entscheidung benötigt bis:** P0 Week 1
**Impact:** MEDIUM (betrifft zukünftige Implementierung)
**Entscheider:** Product Manager + Training-Experte

---

### E1.3: Correlations - Zeitfenster definieren

**Betroffene Platzhalter:** 5
- `correlation_energy_weight_lag`
- `correlation_load_hrv`
- `correlation_load_rhr`
- `correlation_protein_lbm`
- `correlation_sleep_recovery`

**Problem:**
Korrelationen brauchen Mindestdaten. Welches Zeitfenster ist statistisch sinnvoll?

**Optionen:**

| Option | Beschreibung | Pro | Contra |
|--------|--------------|-----|--------|
| **A: `28d`** | Min 21-28 Paare für Reliability | Statistisch robust | Reagiert langsam auf Änderungen |
| **B: `custom`** | Variabel je nach Datenverfügbarkeit | Flexibel | Unklar für User |
| **C: Im Semantic Contract spezifizieren** | Z.B. "28d min, 90d ideal" | Transparent | Komplex |

**Empfehlung Audit-Agent:**
- **Option A (`28d`)** für `time_window`
- **Option C** zusätzlich in `semantic_contract`

**Beispiel:**
```json
{
  "key": "correlation_energy_weight_lag",
  "time_window": "28d",
  "semantic_contract": "Lag-Korrelation (0d/3d/7d/14d) zwischen Energiebilanz und Gewicht. Min 21 Paare (28d) für Reliability, 90d ideal. Explorativ, nicht kausal."
}
```

**Entscheidung benötigt bis:** P0 Week 1
**Impact:** MEDIUM (betrifft Statistik-Interpretation)
**Entscheider:** Tech Lead (Statistik-Know-how)

---

### E1.4: Goals & Focus - Zeitfenster definieren

**Betroffene Platzhalter:** 16
- `active_goals_json`, `active_goals_md`
- `focus_areas_weighted_json`, `focus_areas_weighted_md`, `focus_area_weights_json`
- `top_goal_name`, `top_goal_progress_pct`, `top_goal_status`
- `top_3_goals_behind_schedule`, `top_3_goals_on_track`, `top_3_focus_areas`
- `focus_cat_körper_progress`, `focus_cat_ernährung_progress`, `focus_cat_aktivität_progress`, `focus_cat_recovery_progress`, `focus_cat_vitalwerte_progress`, `focus_cat_mental_progress`, `focus_cat_lebensstil_progress` (jeweils + weight)

**Problem:**
Goals sind Snapshots, aber Progress wird über Zeit berechnet. Wie klassifizieren?

**Optionen:**

| Option | Beschreibung | Pro | Contra |
|--------|--------------|-----|--------|
| **A: `latest`** | Aktueller Stand der Goals | Technisch korrekt (Snapshot) | Impliziert keine Zeit-Dimension |
| **B: `custom`** | Progress-Berechnung ist zeitabhängig | Signalisiert Komplexität | Unklar für Snapshot-Werte |
| **C: Differenzierung** | `active_goals_json`: `latest`, Progress-Felder: `custom` | Präzise | 16 individuelle Entscheidungen |

**Empfehlung Audit-Agent:**
- **Option C** (Differenzierung):
  - **Snapshot-Platzhalter** (active_goals_json, focus_area_weights_json, top_goal_name): `latest`
  - **Progress-Platzhalter** (top_goal_progress_pct, focus_cat_*_progress): `custom` (da verschiedene Ziele verschiedene Zeiträume haben)

**Entscheidung benötigt bis:** P0 Week 1
**Impact:** LOW (primär dokumentarisch)
**Entscheider:** Product Manager

---

### E1.5: Snapshots - Zeitfenster definieren

**Betroffene Platzhalter:** 7
- `bmi`
- `goal_weight`, `goal_bf_pct`
- `waist_hip_ratio`
- `recomposition_quadrant`
- `plateau_detected`
- `top_drivers`

**Problem:**
Einige sind echte Snapshots (bmi, goal_weight), andere berechnete Werte über Zeit (recomposition_quadrant, plateau_detected).

**Optionen:**

| Option | Beschreibung | Pro | Contra |
|--------|--------------|-----|--------|
| **A: Alle `latest`** | Vereinfachung | Einfach | Ungenau für berechnete |
| **B: Differenzierung** | bmi/goal_weight: `latest`, recomposition_quadrant/plateau_detected: `28d` | Präzise | 7 individuelle Entscheidungen |

**Empfehlung Audit-Agent:**
- **Option B**:
  - **Echte Snapshots** (bmi, goal_weight, goal_bf_pct, waist_hip_ratio): `latest`
  - **Berechnete über Zeit** (recomposition_quadrant, plateau_detected, top_drivers): `28d` oder `custom`

**Entscheidung benötigt bis:** P0 Week 1
**Impact:** LOW
**Entscheider:** Tech Lead

---

## KATEGORIE 2: Integration ungenutzter Platzhalter (P2)

### E2.1: Ungenutzte Platzhalter - Roadmap-Priorisierung und Integration-Timeline

**Betroffene Platzhalter:** 67 (ungenutzt)

**Kontext:**
67 Platzhalter (60%) haben 0 Verwendungen. **WICHTIG:** Dies ist kein Deprecation-Bedarf, sondern Integration-Planung.

**Fachliche Klassifizierung (siehe USAGE_ROLE_CLASSIFICATION.md):**
- **30 Platzhalter (45%):** Explizit in Roadmap Phase 0c/1/2 geplant
- **37 Platzhalter (55%):** Fachlich plausibel, noch nicht in Prompts integriert
- **0 Platzhalter:** Redundant oder deprecation-würdig

**Neue Fragestellung:**
Nicht "Behalten oder Deprecaten?", sondern "WANN und WIE integrieren?"

---

**Sub-Entscheidungen:**

#### E2.1.1: Geplante Platzhalter (30) - Integration-Timeline bestätigen

**Platzhalter-Gruppen:**
- **Scores (6):** activity_score, nutrition_score, recovery_score, body_progress_score, goal_progress_score, data_quality_score
  - **Roadmap:** Phase 0c (Multi-Layer Architecture) + Phase 1 (Charts)
- **Correlations (5):** energy_weight_lag, load_hrv, load_rhr, protein_lbm, sleep_recovery
  - **Roadmap:** Phase 2 (Engagement - Korrelationen)
- **Ability Balance (5):** coordination, endurance, mental, mobility, strength
  - **Roadmap:** Phase 1 (Charts - Training Balance)
- **Goals Details (11):** active_goals_json/md, focus_areas_weighted, top_3_goals_*, focus_cat_*_progress
  - **Roadmap:** Phase 0b/0c (Backend DONE, Prompt-Integration ausstehend)
- **Sleep/Plateau/Drivers (3):** sleep_debt, plateau_detected, top_drivers
  - **Roadmap:** Phase 1/2 (Diagnostics)

**Frage:** Timeline bestätigen oder anpassen?

**Optionen:**
- **A: Roadmap wie geplant** - Phase 0c/1/2 (nächste 6-12 Wochen)
- **B: Priorisierung anpassen** - Quick Wins zuerst (z.B. Goals Details sofort)
- **C: Prototyping** - 5-10 Beispiel-Prompts erstellen (Wert demonstrieren)

**Empfehlung:** C → B → A (Prototyping zeigt Wert, dann Priorisierung, dann Roadmap)

---

#### E2.1.2: Plausible Platzhalter (37) - Prompt-Use-Cases identifizieren

**Platzhalter-Gruppen:**
- **Body Deltas (5):** arm_28d_delta, chest_28d_delta, hip_28d_delta, thigh_28d_delta, waist_28d_delta
- **Nutrition Details (6):** energy_deficit_surplus, intake_volatility, nutrition_days, protein_days_in_target, protein_ziel_low/high
- **Training Quality/Load (3):** monotony_score, strain_score, rest_day_compliance
- **Focus Category Weights/Progress (14):** focus_cat_*_weight, focus_cat_*_progress
- **Meta/Convenience (9):** bmi, waist_hip_ratio, datum_heute, zeitraum_*

**Frage:** Für welche Use-Cases Prompt-Templates erstellen?

**Optionen:**
- **A: Alle 37 dokumentieren** - Vollständig, aber aufwändig
- **B: Quick Wins (10-15)** - Offensichtliche Use-Cases zuerst
- **C: Warten bis Bedarf** - Nur auf Anfrage aktivieren

**Empfehlung:** B (10-15 Quick Wins: Body Deltas für Fortschritts-Prompts, Nutrition Details für Coaching-Prompts, Focus Category für Dashboard-Widgets)

---

**Entscheidung benötigt bis:** P2 Week 4
**Impact:** MEDIUM (Prompt-Bibliothek Vollständigkeit)
**Entscheider:** Product Manager + Tech Lead
**Methode:** Integration-Planungs-Meeting (4-6h, siehe Maßnahmenplan P2.2 REVIDIERT)

---

## KATEGORIE 3: Production-Readiness-Kriterien (P2)

### E3.1: Welche Platzhalter sind Production-Ready?

**Problem:**
Aktuell haben alle 111 `schema_status: draft`. Welche Kriterien für `production`?

**Vorgeschlagene Kriterien (aus Maßnahmenplan):**
1. `metadata_completeness_score >= 80`
2. `used_by.prompts.length >= 1 OR used_by.pipelines.length >= 1`
3. `time_window != 'unknown'`
4. `category != 'Unknown'`
5. `description != 'No description available'`
6. `confidence_logic != null OR (type == 'atomic' AND time_window == 'latest')`
7. `known_issues.length == 0`

**Frage:** Sind diese Kriterien zu streng/zu locker?

**Optionen:**
- **A: Wie vorgeschlagen** - Balanced
- **B: Strengere Kriterien** - Z.B. `used_by >= 3`, `completeness_score >= 90`
- **C: Lockerere Kriterien** - Z.B. `completeness_score >= 60`, keine Usage-Requirement

**Empfehlung:** A (wie vorgeschlagen)

**Zusatzfrage:** Soll es Zwischen-Status geben (`beta`, `stable`)?

**Optionen:**
- **A: Nur draft/production** - Einfach
- **B: draft/beta/stable/production** - Differenzierter

**Empfehlung:** B (mehr Nuancen ermöglichen schrittweise Freigabe)

**Entscheidung benötigt bis:** P2 Week 4
**Impact:** MEDIUM (Governance)
**Entscheider:** Tech Lead + Product Manager

---

## KATEGORIE 4: Neue Platzhalter (FUTURE)

### E4.1: Requirements Dev vs. Extended Catalog - Wie priorisieren?

**Problem:**
- **requirements_dev.md** schlägt 27 neue Platzhalter vor (P1-P27)
- **Extended Catalog** hat bereits 111
- Viele der "neuen" sind evtl. schon abgedeckt

**Frage:** Sollen die 27 P1-P27 implementiert werden, oder sind sie durch bestehende abgedeckt?

**Beispiele:**
- **P1: `goal_summary_json`** - Abgedeckt durch `active_goals_json` + `active_goals_md`?
- **P2: `focus_area_summary_json`** - Abgedeckt durch `focus_areas_weighted_json`?
- **P5: `domain_availability_json`** - Neu, nicht vorhanden
- **P12: `body_change_summary_json`** - Teilweise durch `caliper_summary`, `circ_summary`

**Empfehlung:**
- **Mapping-Exercise:** Neue vs. Bestehende
- **Gap-Analyse:** Welche sind echte Lücken?
- **Priorisierung:** Nur echte Gaps implementieren

**Entscheidung benötigt bis:** Nach P2 (Phase 1b Planning)
**Impact:** HIGH (Feature-Roadmap)
**Entscheider:** Product Manager + Tech Lead

---

## KATEGORIE 5: Governance-Prozesse (POST-AUDIT)

### E5.1: Wie werden neue Platzhalter künftig validiert?

**Problem:**
Aktuell gibt es keine systematische Validierung neuer Platzhalter gegen Normative Spec.

**Frage:** Soll ein Pre-Commit-Hook/CI-Check eingeführt werden?

**Optionen:**
- **A: Manuelle Reviews** - Flexibel, aber fehleranfällig
- **B: Automated Checks** - Robust, aber Aufwand für Setup
- **C: Hybrid** - Automated Checks + manuelle Review für komplexe Fälle

**Empfehlung:** C (Hybrid)

**Entscheidung benötigt bis:** Nach P2 (Tooling-Phase)
**Impact:** HIGH (langfristige Qualität)
**Entscheider:** Tech Lead

---

### E5.2: Wer ist Owner für Placeholder-Governance?

**Problem:**
Aktuell kein klarer Owner für Placeholder-Lifecycle.

**Frage:** Soll es eine dedizierte Rolle geben?

**Optionen:**
- **A: Tech Lead** - Technische Verantwortung
- **B: Product Manager** - Fachliche Verantwortung
- **C: Shared (beide)** - Consensus-basiert
- **D: Dedizierte Rolle "Data-Contract-Owner"** - Spezialisiert

**Empfehlung:** C (Shared) für jetzt, D langfristig

**Entscheidung benötigt bis:** Nach P2
**Impact:** MEDIUM (Governance)
**Entscheider:** Management

---

## KATEGORIE 6: Technische Schulden (POST-P2)

### E6.1: Legacy-String "nicht verfügbar" - Wann abschalten?

**Problem:**
P1.6 führt Dual-Mode ein (Legacy + Structured). Wann soll Legacy deprecated werden?

**Optionen:**
- **A: Nach 3 Monaten** - Schnell
- **B: Nach 6 Monaten** - Standard
- **C: Nach 12 Monaten** - Konservativ
- **D: Nie (dauerhaft Dual-Mode)** - Ewig Backward-Compatible

**Empfehlung:** B (6 Monate) mit klarer Migration-Guidance

**Entscheidung benötigt bis:** P1 Abschluss (Sunset-Datum festlegen)
**Impact:** MEDIUM (Breaking Change für Prompts)
**Entscheider:** Tech Lead + Prompt-Autoren

---

## ZUSAMMENFASSUNG OFFENER ENTSCHEIDUNGEN

| ID | Kategorie | Entscheidung | Dringlichkeit | Entscheider |
|----|-----------|--------------|---------------|-------------|
| **E1.1** | Zeitfenster Scores | custom/mixed/dominant? | 🔴 P0 Week 1 | Product |
| **E1.2** | Zeitfenster Ability Balance | 28d/14d/latest? | 🔴 P0 Week 1 | Product + Training-Expert |
| **E1.3** | Zeitfenster Correlations | 28d mit Min-Data? | 🔴 P0 Week 1 | Tech Lead |
| **E1.4** | Zeitfenster Goals & Focus | latest/custom/differenziert? | 🔴 P0 Week 1 | Product |
| **E1.5** | Zeitfenster Snapshots | latest/differenziert? | 🔴 P0 Week 1 | Tech Lead |
| **E2.1** | Integration-Timeline | 67 ungenutzte integrieren | 🟡 P2 Week 4 | Product |
| **E3.1** | Production-Kriterien | draft/beta/stable/production? | 🟡 P2 Week 4 | Tech + Product |
| **E4.1** | Neue Platzhalter P1-P27 | Welche implementieren? | 🟢 Post-P2 | Product |
| **E5.1** | Validierungs-Prozess | Automated/Manual/Hybrid? | 🟢 Post-P2 | Tech Lead |
| **E5.2** | Governance-Owner | Wer verantwortet Placeholders? | 🟢 Post-P2 | Management |
| **E6.1** | Legacy-Sunset | Wann "nicht verfügbar" abschalten? | 🟡 P1 Abschluss | Tech Lead |

**Legende:**
- 🔴 BLOCKING (P0) - Entscheidung innerhalb Week 1 benötigt
- 🟡 HIGH (P1-P2) - Entscheidung innerhalb Week 4-5 benötigt
- 🟢 MEDIUM (Post-P2) - Kann warten

---

## EMPFOHLENER ENTSCHEIDUNGS-PROZESS

### Week 1 (P0 Kickoff)
1. **Meeting (2h):** Product + Tech Lead + Training-Expert
2. **Agenda:**
   - E1.1-E1.5: Alle Zeitfenster-Entscheidungen
   - Decision-Log erstellen
3. **Output:** Entschiedene Zeitfenster für alle 39 unkla

ren Platzhalter

### Week 4 (P2)
1. **Meeting (2h):** Product + Tech Lead
2. **Agenda:**
   - E2.1: Deprecation-Review (67 ungenutzte)
   - E3.1: Production-Kriterien
3. **Output:** Deprecation-Liste, Production-Kriterien finalisiert

### Post-P2
1. **Meeting (1h):** Management + Tech + Product
2. **Agenda:**
   - E4.1: Neue Platzhalter-Roadmap
   - E5.1-E5.2: Governance-Prozesse
   - E6.1: Legacy-Sunset-Datum
3. **Output:** Langfristige Placeholder-Governance etabliert

---

## NÄCHSTE SCHRITTE

1. **Dieses Dokument reviewen** mit Product Manager
2. **P0-Meeting ansetzen** (Week 1) für Zeitfenster-Entscheidungen
3. **Decision-Log starten** (Living Document)
4. **Nach Entscheidungen:** Maßnahmenplan P0 final anpassen

---

**Offene Entscheidungen dokumentiert von:** Claude Code (Lead Audit Agent)
**Review benötigt von:** Product Manager + Tech Lead
**Deadline kritische Entscheidungen:** P0 Week 1 (innerhalb 1 Woche)