mitai-jinkendo/.claude/docs/audit/platzhalter/placeholder_requirements_for_development.md

# Placeholder-Gap- und Governance-Dokument für Vibe-Coding / Entwickler

**Datei:** `placeholder_requirements_for_development.md`  
**Zweck:** Arbeitsgrundlage für Entwickler, damit die Prompt-Bibliothek mit stabilen, fachlich sauberen Platzhaltern betrieben werden kann.  
**Status:** Draft / arbeitsfähig  
**Bezug:** Prompt-Bibliothek, Report-Steckbriefe, bestehender Placeholder-Export, Datenarchitektur

---

## 1. Ziel dieses Dokuments

Dieses Dokument beschreibt:

1. **welche Platzhalter bereits vorhanden und nutzbar sind**
2. **welche Platzhalter fachlich geschärft werden müssen**
3. **welche neuen Platzhalter für V1 zusätzlich bereitgestellt werden sollten**
4. **welche Platzhalter nur als spätere Erweiterung gelten**
5. **welche Governance-Regeln für Benennung, Semantik und Versionierung gelten**

Wichtig:  
Die Prompt-Bibliothek darf **nicht** darauf angewiesen sein, dass Folgechats spontan neue Platzhalter erfinden oder bestehende umdeuten.  
Die API-/Export-Seite muss deshalb eine **kontrollierte, stabile Placeholder-Oberfläche** bereitstellen.

---

## 2. Grundprinzipien für Platzhalter

### 2.1 Platzhalter sind API-Verträge
Ein Platzhalter ist kein freier Text, sondern ein **stabiler Vertrag** zwischen:
- Datenmodell / Berechnungslogik
- Export-/Aggregationsebene
- Prompt-System
- UI / Auswertung / QA

### 2.2 Platzhalter dürfen nicht stillschweigend umdefiniert werden
Ein einmal eingeführter Platzhalter darf nicht:
- semantisch verändert werden
- in einem anderen Zeitraum berechnet werden
- seine Einheit ändern
- stillschweigend von Rohwert auf Trendwert wechseln

### 2.3 Fehlende Werte müssen explizit sein
Wenn ein Wert nicht berechnet werden kann, soll dies **strukturiert** erfolgen, nicht als vager Freitext.

Bevorzugt:
- `null`
- oder ein strukturierter Verfügbarkeitsstatus

Nur wenn das bestehende System es erzwingt, darf vorläufig `"nicht verfügbar"` verwendet werden.

### 2.4 Platzhalter sollen möglichst atomar sein
Bevorzugt:
- einzelne, klar definierte Felder  
Nicht bevorzugt:
- sehr große, uneinheitliche Freitext-Blobs, die mehrere Logiken mischen

Trotzdem dürfen kompakte Summary-Platzhalter als Zusatz bleiben, z. B. für einfache Prompts oder UI-Kurztexte.

### 2.5 Zeitbezug muss immer eindeutig sein
Jeder zeitabhängige Platzhalter braucht klaren Fensterbezug:
- `*_today`
- `*_7d`
- `*_14d`
- `*_28d`
- `*_90d`

---

## 3. Bereits vorhandene und gut nutzbare Platzhalter

Diese Platzhalter sind bereits vorhanden und für V1 sinnvoll nutzbar.

## 3.1 Profil / Stammdaten
- `name`
- `age`
- `height`
- `geschlecht`

## 3.2 Körper
- `weight_aktuell`
- `weight_trend`
- `kf_aktuell`
- `bmi`
- `weight_7d_median`
- `waist_hip_ratio`
- `caliper_summary`
- `circ_summary`

## 3.3 Ernährung
- `kcal_avg`
- `protein_avg`
- `carb_avg`
- `fat_avg`
- `energy_balance_7d`
- `protein_g_per_kg`
- `protein_adequacy_28d`
- `macro_consistency_score`
- `energy_deficit_surplus`

## 3.4 Training / Aktivität
- `activity_summary`
- `activity_detail`
- `trainingstyp_verteilung`
- `training_minutes_week`
- `training_frequency_7d`
- `quality_sessions_pct`
- `proxy_internal_load_7d`
- `monotony_score`
- `strain_score`
- `rest_day_compliance`

## 3.5 Schlaf / Erholung
- `sleep_avg_duration`
- `sleep_avg_quality`
- `rest_days_count`
- `sleep_avg_duration_7d`
- `sleep_debt_hours`
- `sleep_regularity_proxy`
- `sleep_quality_7d`

## 3.6 Vitalwerte
- `vitals_avg_hr`
- `vitals_avg_hrv`
- `vitals_vo2_max`
- `rhr_vs_baseline_pct`
- `vo2max_trend_28d`

## 3.7 Scores / Meta
- `nutrition_score`
- `activity_score`
- `recovery_score`
- `data_quality_score`

## 3.8 Ziele / Fokus
- `top_goal_name`
- `top_goal_progress_pct`
- `top_goal_status`
- `top_focus_area_name`
- `top_focus_area_progress`
- `focus_cat_körper_progress`
- `focus_cat_körper_weight`
- `focus_cat_ernährung_progress`
- `focus_cat_ernährung_weight`
- `focus_cat_aktivität_progress`
- `focus_cat_aktivität_weight`
- `focus_cat_recovery_progress`
- `focus_cat_recovery_weight`
- `focus_cat_vitalwerte_progress`
- `focus_cat_vitalwerte_weight`
- `focus_cat_mental_progress`
- `focus_cat_mental_weight`
- `focus_cat_lebensstil_progress`
- `focus_cat_lebensstil_weight`

## 3.9 Zeitraum
- `datum_heute`
- `zeitraum_7d`
- `zeitraum_30d`
- `zeitraum_90d`

## 3.10 Korrelation / Diagnose
- `correlation_energy_weight_lag`

---

## 4. Bereits vorhandene Platzhalter mit Schärfungsbedarf

Diese Platzhalter existieren, sind aber fachlich oder operativ noch nicht sauber genug.

## 4.1 "nicht verfügbar" als String
Betroffen u. a.:
- `goal_progress_score`
- `body_progress_score`
- `fm_28d_change`
- `lbm_28d_change`
- `waist_28d_delta`
- `recomposition_quadrant`
- `ability_balance_strength`
- `ability_balance_endurance`
- `hrv_vs_baseline_pct`
- weitere ähnliche Felder

### Problem
- Die Prompt-Logik muss String-Inhalte interpretieren.
- Folgeprompts können schwer unterscheiden zwischen:
  - echter Null
  - fehlendem Wert
  - noch nicht implementiert
  - Daten reichen nicht

### Empfehlung
Zusätzlich zu jedem kritischen Feld:
- `*_available: true|false`
- optional `*_reason_unavailable`

Oder besser:
- ein strukturiertes Domain-Availability-Objekt

---

## 4.2 Prozent-/Score-Platzhalter ohne standardisierte Skala
Betroffen:
- `quality_sessions_pct`
- `protein_adequacy_28d`
- `macro_consistency_score`
- `nutrition_score`
- `activity_score`
- `recovery_score`
- `data_quality_score`

### Problem
Die Skala ist im Prompt nicht immer selbsterklärend:
- 0–100?
- Prozent?
- normierter Score?
- je höher desto besser?

### Empfehlung
Für jeden solchen Platzhalter intern dokumentieren:
- Skala
- Richtung
- Berechnungsbasis
- sinnvolle Interpretationszonen

Optional zusätzliche Entwickler-Metadaten:
- `score_meta_<name>`

---

## 4.3 Summary-Felder als alleinige Quelle
Betroffen:
- `activity_summary`
- `caliper_summary`
- `circ_summary`

### Problem
Diese Felder sind nützlich für kompakte Reports, aber für robuste Mehrstufigkeit oft zu grob.

### Empfehlung
Summary-Felder behalten, aber ergänzen durch strukturierte Roh-/Aggregatfelder.

---

## 4.4 Fokuskategorien nicht sauber auf 100 normiert
Im Export fallen z. B. Gewichte wie `135.0` oder andere Summen auf.

### Problem
Für Prompts und Zielgewichtung ist unklar:
- sind das Rohgewichte?
- normierte Gewichte?
- gruppeninterne Punkte?
- Prozentangaben?

### Empfehlung
Klar trennen zwischen:
- `focus_cat_*_weight_raw`
- `focus_cat_*_weight_normalized`

Und ebenso für einzelne Fokusbereiche.

---

## 4.5 Zeitfenster-Mischung
Einige Felder sind 7d, andere 14d, 28d oder unklar verdichtet.

### Problem
Prompts können unabsichtlich Zeitfenster vergleichen, die nicht zusammenpassen.

### Empfehlung
Zeitfenster im Feldnamen vereinheitlichen und konsequent dokumentieren.

---

## 5. Neue Platzhalter, die für V1 zusätzlich bereitgestellt werden sollten

Diese Liste ist die wichtigste operative To-do-Liste für die Entwicklung.

## 5.1 Höchste Priorität – Zielsystem / Fokus / Kontext

### P1. `goal_summary_json`
**Zweck:** kompakte, strukturierte Zielübersicht für Zielreports und zielgewichtete Synthesen.

**Sollinhalt:**
- Liste aktiver Ziele
- je Ziel:
  - ID
  - Name
  - Typ
  - Status
  - Startwert
  - Zielwert
  - aktueller Wert
  - Fortschritt
  - Zieltermin (falls vorhanden)
  - primary_flag
  - zugeordnete Fokusbereiche

**Warum wichtig:**  
Die aktuelle Prompt-Bibliothek braucht mehr als nur `top_goal_name`.

---

### P2. `focus_area_summary_json`
**Zweck:** strukturierte Liste der aktiven Fokusbereiche.

**Sollinhalt:**
- Fokusbereichsname
- Gruppe/Kategorie
- Rohgewicht
- normiertes Gewicht
- aktueller Progress
- verknüpfte Ziele

**Warum wichtig:**  
Top-Focus allein reicht für personalisierte Reports nicht.

---

### P3. `goal_progress_score_available`
**Typ:** bool  
**Warum:** sauber zwischen fehlend und vorhanden unterscheiden.

### P4. `body_progress_score_available`
**Typ:** bool  
**Warum:** dito.

---

## 5.2 Höchste Priorität – Domain Availability / Confidence

### P5. `domain_availability_json`
**Zweck:** zentrale Verfügbarkeit pro Domäne.

**Sollinhalt:**
- body
- nutrition
- activity
- sleep
- recovery
- vitals
- goals
- focus_areas
- correlations

jeweils mit:
- available
- confidence
- main_gaps
- last_valid_window

**Warum wichtig:**  
Vereinfacht Fallbacks und verhindert Scheinpräzision.

---

### P6. `domain_confidence_json`
Falls `domain_availability_json` nicht reicht oder zu groß wird.

---

### P7. `critical_missing_fields_json`
**Zweck:** welche fehlenden Daten würden den größten Erkenntnisgewinn bringen?

**Warum wichtig:**  
Für Datenqualitätsreport und Nutzerführung.

---

## 5.3 Höchste Priorität – Körperentwicklung

### P8. `fm_28d_change_available`
### P9. `lbm_28d_change_available`
### P10. `waist_28d_delta_available`
### P11. `recomposition_quadrant_available`

**Warum:**  
Körper- und Plateau-Reports brauchen robuste Verfügbarkeitslogik.

---

### P12. `body_change_summary_json`
**Zweck:** strukturierte Körperentwicklung.

**Sollinhalt:**
- weight trend
- FM delta
- LBM delta
- waist delta
- hip delta
- recomposition quadrant
- confidence

---

## 5.4 Höchste Priorität – Training / Belastung

### P13. `activity_structure_json`
**Zweck:** kompakter Trainingsstrukturblock.

**Sollinhalt:**
- Volumen
- Frequenz
- Typverteilung
- Qualitätsanteil
- Lastniveau
- Monotonie
- Strain
- Rest-day compliance
- auffällige Muster

---

### P14. `training_quality_score`
**Zweck:** standardisierte Trainingsqualitätsbewertung über Sessions hinweg

**Warum:**  
Aktuell gibt es `quality_sessions_pct`, aber noch keinen robusten verdichteten Qualitätsanker.

---

### P15. `load_balance_class`
Wertebeispiele:
- low
- moderate
- high
- strained

**Warum:**  
Erleichtert Diagnose-Prompts.

---

## 5.5 Höchste Priorität – Schlaf / Recovery / Vitals

### P16. `sleep_summary_json`
**Sollinhalt:**
- duration
- quality
- debt
- regularity
- trend
- confidence

### P17. `recovery_summary_json`
**Sollinhalt:**
- recovery score
- main drivers
- RHR status
- HRV status
- recent load interaction
- confidence

### P18. `vitals_summary_json`
**Sollinhalt:**
- resting HR
- HRV
- VO2max
- trend
- baseline deviation
- confidence

### P19. `hrv_vs_baseline_pct_available`
### P20. `rhr_vs_baseline_pct_available`

---

## 5.6 Höchste Priorität – Korrelation / Diagnose

### P21. `correlation_summary_json`
**Zweck:** strukturierte Zusammenfassung mehrerer Korrelationen / Lag-Beziehungen.

**Sollinhalt:**
- energy_weight_lag
- training_hrv_lag
- training_rhr_lag
- sleep_recovery_lag
- confidence je Zusammenhang

---

### P22. `plateau_status`
Wertebeispiele:
- likely
- possible
- not_detected
- insufficient_data

### P23. `top_drivers_positive_json`
### P24. `top_drivers_negative_json`

**Warum:**  
Top-Driver-Report und Plateau-Detektor profitieren stark von einer vorberechneten Zwischenebene.

---

## 5.7 Höchste Priorität – Energieverfügbarkeit / Schutzlogik

### P25. `underfueling_risk_flag`
**Typ:** bool / enum

### P26. `underfueling_risk_reason`
**Typ:** text / enum / json

### P27. `energy_availability_summary_json`
**Sollinhalt:**
- intake adequacy
- deficit magnitude
- load context
- recovery context
- warning level
- confidence

---

## 6. Mittlere Priorität – sollte bald folgen

## 6.1 Gesundheitsstabilität
### P28. `health_stability_score`
### P29. `health_stability_summary_json`

## 6.2 Blutdruck
### P30. `blood_pressure_summary_json`
**Sollinhalt:**
- mean systolic/diastolic
- category
- contexts
- trend
- irregularity flags
- confidence

## 6.3 Fokus-/Zielgewichtung
### P31. `goal_weighted_priority_json`
**Zweck:** priorisierte Ziel-/Fokuslogik für Synthese

## 6.4 Reporting-Hilfsfelder
### P32. `main_constraint_json`
### P33. `main_strength_json`
### P34. `next_best_actions_json`

---

## 7. Niedrigere Priorität / spätere Ausbaustufe

Diese Platzhalter sind wertvoll, aber für V1 nicht zwingend:

- `session_rpe`
- `fatigue_score`
- `pain_flag`
- `illness_flag`
- `travel_flag`
- `competition_flag`
- `measurement_time_consistency`
- `training_age`
- `secondary_goals_json`
- `waist_to_height_ratio`
- `sleep_segment_quality_score`
- `steps_summary_json`

---

## 8. Platzhalter, die geschärft statt neu erfunden werden sollten

Statt wild neue Namen einzuführen, sollten folgende Bereiche zuerst **semantisch sauber definiert** werden.

## 8.1 Goal / Focus
Bestehend, aber zu flach:
- `top_goal_name`
- `top_goal_progress_pct`
- `top_focus_area_name`
- `top_focus_area_progress`

**Schärfung:**  
Ergänzen durch strukturierte JSONs, nicht ersetzen.

## 8.2 Körperentwicklung
Bestehend, aber oft nicht verfügbar:
- `fm_28d_change`
- `lbm_28d_change`
- `waist_28d_delta`
- `recomposition_quadrant`

**Schärfung:**  
Verfügbarkeitsflags + strukturierte Summary.

## 8.3 Activity-Qualität
Bestehend:
- `quality_sessions_pct`

**Schärfung:**  
ergänzen durch:
- `training_quality_score`
- ggf. `quality_sessions_count`
- optional `quality_definition_version`

## 8.4 Recovery
Bestehend:
- `recovery_score`

**Schärfung:**  
ergänzen durch Komponenten-/Treiberdarstellung.

## 8.5 Data Quality
Bestehend:
- `data_quality_score`

**Schärfung:**  
ergänzen durch Domain-Ebene und konkrete Lückenbeschreibung.

---

## 9. Governance-Regeln für Platzhalter

Diese Regeln sollten für Entwicklung und Prompting verbindlich sein.

### G1. Keine eigenmächtige Umbenennung
Bestehende Platzhalter dürfen nicht ohne Migration umbenannt werden.

### G2. Keine stillschweigende Semantikänderung
Wenn Berechnungslogik geändert wird, braucht der Platzhalter:
- Versionierung intern
- oder einen neuen Namen

### G3. Neue Platzhalter nur kontrolliert
Neue Platzhalter nur einführen, wenn:
- Zweck klar
- Datenquelle klar
- Zeitfenster klar
- Einheit klar
- Fallback klar

### G4. JSON vor Freitext
Für komplexe Mehrstufenlogik sollen neue Platzhalter bevorzugt als strukturierte JSON-Container bereitgestellt werden.

### G5. Zeitfenster im Namen
Zeitfenster müssen im Namen explizit sein, falls nicht universell.

### G6. Verfügbarkeit trennen von Inhalt
Für kritische Felder besser:
- Wert
- Verfügbarkeitsflag
- optional Grund

### G7. Keine Ad-hoc-Platzhalter in Folgechats
Folgechats für Prompt-Ausarbeitung dürfen keine neuen Platzhalter stillschweigend voraussetzen.

---

## 10. Konkrete Entwickler-Backlog-Empfehlung

## Sprint / Paket 1 – notwendig für robuste V1-Reports
1. `goal_summary_json`
2. `focus_area_summary_json`
3. `domain_availability_json`
4. `critical_missing_fields_json`
5. Verfügbarkeitsflags für Body-Change-Felder
6. `sleep_summary_json`
7. `recovery_summary_json`
8. `activity_structure_json`
9. `correlation_summary_json`
10. `plateau_status`

## Sprint / Paket 2 – starke Verbesserung der Ziel- und Diagnoseebene
1. `top_drivers_positive_json`
2. `top_drivers_negative_json`
3. `energy_availability_summary_json`
4. `underfueling_risk_flag`
5. `health_stability_score`
6. `blood_pressure_summary_json`
7. `goal_weighted_priority_json`

## Sprint / Paket 3 – spätere Verfeinerung
1. `training_quality_score`
2. `session_rpe`
3. `fatigue_score`
4. `measurement_time_consistency`
5. `illness_flag` / `travel_flag`
6. `waist_to_height_ratio`

---

## 11. Abnahmekriterien für die Placeholder-Schicht

Die Placeholder-Schicht ist fachlich gut genug, wenn:

1. **alle Core-Reports der V1-Bibliothek ohne stillschweigende Erfindungen lauffähig sind**
2. fehlende Werte **strukturiert** behandelt werden können
3. Ziel-/Fokus-Logik nicht nur über ein einzelnes „Top“-Feld abgebildet wird
4. Datenqualität und Confidence nicht nur global, sondern domänenspezifisch beschrieben werden
5. Diagnose-Reports mindestens auf vorbereiteten Zwischenobjekten statt nur Freitextsummaries aufsetzen können

---

## 12. Kurzfazit

Für V1 ist die Placeholder-Basis bereits gut, aber noch nicht stabil genug für eine große professionelle Prompt-Bibliothek.  
Der größte Handlungsbedarf liegt in vier Bereichen:

- **strukturierte Ziel-/Fokus-JSONs**
- **domänenspezifische Availability-/Confidence-Objekte**
- **robustere Diagnose-/Driver-/Plateau-Zwischenfelder**
- **saubere Verfügbarkeits- und Schärfungslogik für kritische Body-/Recovery-Felder**

Dieses Dokument ist bewusst entwicklungsnah formuliert und soll als Arbeitsgrundlage für die Implementierung dienen.