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.