mitai-jinkendo/.claude/docs/functional/AI_PROMPTS.md

# Fachliche Anforderungen: KI-Prompt Flexibilisierung
**Modul:** v9f  
**Status:** Fachlich freigegeben, technische Implementierung ausstehend  
**Letzte Aktualisierung:** März 2026

---

## 1. Überblick

Das bestehende KI-Prompt-System wird von einer fixen Sammlung vordefinierter
Prompts zu einer vollständig konfigurierbaren Prompt-Bibliothek erweitert.
Admins können Prompts kategorisieren, duplizieren, bearbeiten und mit einem
visuellen Platzhalter-Browser ausstatten. Die Pipeline wird konfigurierbar –
mehrere Konfigurationen für unterschiedliche Analysezwecke sind möglich.

---

## 2. Prompt-Bibliothek

### 2.1 Kategorien

Alle Prompts werden einer Kategorie zugeordnet:

| Kategorie | Beschreibung | Beispiel-Prompts |
|-----------|-------------|-----------------|
| Körper | Gewicht, KF, Umfänge, Caliper | Körperkomposition, Gewichtstrend |
| Ernährung | Kalorien, Makros, Timing | Kalorienbilanz, Proteinversorgung |
| Training | Volumen, Typen, HF | Trainingsanalyse, Erholungsstatus |
| Schlaf | Qualität, Dauer, Muster | Schlafauswertung, Schlaftrend |
| Vitalwerte | Ruhepuls, HRV, VO2Max | Leistungsfähigkeit, Erholung |
| Mentales | Stress, Stimmung, Energie | Wohlbefinden, Stressanalyse |
| Ziele | Fortschritt, Prognose, Zeitplan | Zielerreichung, Zeitplanung |
| Ganzheitlich | Korrelationen, Übersicht | Gesamtanalyse, Pipeline-Synthese |

### 2.2 Prompt-Verwaltung (Admin)

Ein Admin kann mit jedem Prompt folgendes tun:

**Aktivieren / Deaktivieren**
- Inaktive Prompts sind für Nutzer nicht sichtbar und nicht ausführbar
- Pipeline-Prompts können separat aktiviert/deaktiviert werden

**Duplizieren und anpassen**
- Bestehenden Prompt als Vorlage kopieren
- Kopie erhält Suffix " (Kopie)" und kann unabhängig bearbeitet werden

**Neu erstellen**
- Titel, Beschreibung, Kategorie, Template
- Platzhalter über den Platzhalter-Browser einfügen (siehe Abschnitt 3)

**Kategorie zuordnen**
- Beim Erstellen und Bearbeiten wählbar
- Nachträgliche Änderung möglich

**Reihenfolge festlegen**
- Drag & Drop oder Zahleneingabe (sort_order)
- Reihenfolge bestimmt Anzeige in der Nutzer-Ansicht

**Auf Standard zurücksetzen**
- Systemseitig definierte Prompts haben einen "Standard"-Zustand
- Reset stellt Original-Template wieder her
- Eigens erstellte Prompts haben keinen Standard-Reset

### 2.3 Prompt-Felder

Jeder Prompt hat:
- **Titel** – kurzer Name (z.B. "Körperkomposition")
- **Beschreibung** – wofür ist dieser Prompt? (für Admin sichtbar)
- **Kategorie** – aus der Kategorienliste
- **Template** – der eigentliche Prompt-Text mit Platzhaltern
- **Aktiv** – true/false
- **Reihenfolge** – Zahl für Sortierung
- **Typ** – `single` (Einzelanalyse) oder `pipeline` (Pipeline-Stufe)
- **Pipeline-Stufe** – nur bei Typ `pipeline`: Stufen-Nummer (1, 2, 3...)

---

## 3. Platzhalter-System

### 3.1 Platzhalter-Browser

Beim Bearbeiten eines Prompts steht ein visueller Platzhalter-Browser zur
Verfügung – Admin tippt Platzhalter nicht mehr manuell, sondern wählt sie aus.

**Funktionen:**
- **Filterung nach Kategorie** – zeigt nur Platzhalter der gewählten Kategorie
- **Beispielwert** – zeigt was der Platzhalter aktuell mit echten Daten ausgeben würde
- **Klick zum Einfügen** – Platzhalter wird an Cursor-Position ins Template eingefügt
- **Warnung bei fehlendem Platzhalter** – wenn ein eingetippter Platzhalter nicht existiert
- **Warnung bei fehlenden Daten** – wenn Daten für diesen Platzhalter nicht vorhanden sind (z.B. noch kein Schlaf-Tracking)

### 3.2 Prompt-Vorschau

Vor dem Speichern kann der Admin eine Vorschau anfordern:
- System befüllt alle Platzhalter mit echten aktuellen Daten
- Zeigt den fertigen Prompt-Text wie er an die KI gesendet würde
- KI wird dabei **nicht** aufgerufen – nur der Prompt-Text wird angezeigt

### 3.3 Platzhalter-Kategorien und Übersicht

**Körper:**
```
{{weight_aktuell}}         → "86,1 kg"
{{weight_trend}}           → "sinkend (-0,8 kg letzte 4 Wochen)"
{{kf_aktuell}}             → "19,9%"
{{kf_trend}}               → "stabil"
{{magermasse}}             → "69,4 kg"
{{whr}}                    → "0,90"
{{whtr}}                   → "0,51"
{{bmi}}                    → "27,2"
{{circ_summary}}           → "Taille: 88cm, Hüfte: 98cm, ..."
{{caliper_summary}}        → "KF nach Jackson/Pollock: 19,9%"
```

**Ernährung:**
```
{{kcal_avg}}               → "1.847 kcal/Tag (Ø 30 Tage)"
{{protein_avg}}            → "138g/Tag"
{{protein_ziel_low}}       → "138"
{{protein_ziel_high}}      → "172"
{{fat_avg}}                → "72g/Tag"
{{carb_avg}}               → "195g/Tag"
{{nutrition_summary}}      → kompakte Zusammenfassung
{{nutrition_detail}}       → ausführliche Tabelle
{{nutrition_days}}         → "28 Tage mit Daten"
{{activity_kcal_summary}}  → "Ø 320 kcal aktiver Verbrauch/Tag"
```

**Training:**
```
{{activity_summary}}           → kompakte Zusammenfassung
{{activity_detail}}            → ausführliche Liste
{{trainingstyp_verteilung}}    → "60% Kraft, 30% Cardio, 10% Mobility"
{{trainingstyp_haupttyp}}      → "Kraft" (häufigster Typ)
{{ruhetage_letzte_woche}}      → "2"
{{trainingsphase}}             → "Aufbau / Erholung / Plateau"
{{hf_zonen_verteilung}}        → "Zone 2: 45%, Zone 3: 35%, Zone 4: 20%"

{{faehigkeiten_analyse}}       → Detaillierte Analyse der trainierten Fähigkeiten
{{faehigkeiten_koordinativ}}   → "Orientierung: 3/14 Einheiten, Gleichgewicht: 5/14, ..."
{{faehigkeiten_konditionell}}  → "Kraft: 8/14, Ausdauer: 4/14, Schnelligkeit: 2/14, Flexibilität: 3/14"
{{faehigkeiten_kognitiv}}      → "Konzentration: 2/14, Entscheidung: 1/14, ..."
{{faehigkeiten_psychisch}}     → "Willenskraft: 5/14, Stressresistenz: 2/14, ..."
{{faehigkeiten_taktisch}}      → "Timing: 1/14, Antizipation: 2/14, ..."
{{faehigkeiten_balance}}       → "Ausgewogen / Einseitig + Empfehlung"
```

**Fähigkeiten-System (v9d Integration):**
- Jeder Trainingstyp ist mit 1-N Fähigkeiten aus 5 Dimensionen verknüpft
- KI erhält aggregierte Statistik: wie oft wurden welche Fähigkeiten trainiert
- Ermöglicht Aussagen wie: "Dein Training fokussiert stark auf Kraft (8 von 14 Einheiten), aber koordinative Fähigkeiten kommen zu kurz."
- Basis für gezielte Trainingsempfehlungen

**Herzfrequenz & Vitalwerte:**
```
{{ruhepuls_aktuell}}       → "52 bpm"
{{ruhepuls_trend}}         → "sinkend (-3 bpm letzte 4 Wochen)"
{{hrv_aktuell}}            → "58 ms"
{{hrv_baseline}}           → "62 ms (30-Tage-Durchschnitt)"
{{erholungsstatus}}        → "gut / teilweise / schlecht"
{{vo2max}}                 → "48,2 ml/kg/min"
```

**Schlaf:**
```
{{schlaf_avg_dauer}}       → "7,2h/Nacht (Ø 7 Tage)"
{{schlaf_qualitaet}}       → "3,8/5 (Ø 7 Tage)"
{{schlaf_trend}}           → "stabil"
{{schlaf_detail}}          → ausführliche Tabelle
```

**Mentales:**
```
{{energie_niveau}}         → "3,2/5 (Ø 7 Tage)"
{{stress_niveau}}          → "2,8/5 (Ø 7 Tage)"
{{stimmung}}               → "3,9/5 (Ø 7 Tage)"
{{meditation_streak}}      → "5 Tage in Folge"
```

**Ziele:**
```
{{goal_weight}}            → "82 kg"
{{goal_bf_pct}}            → "14%"
{{goal_name}}              → "Muskelaufbau"
{{ziel_fortschritt}}       → "Gewicht: 72% erreicht, KF: 45% erreicht"
{{ziel_prognose}}          → "Ziel voraussichtlich in 8 Wochen erreicht"
```

**Profil:**
```
{{name}}                   → "Lars"
{{geschlecht}}             → "männlich"
{{height}}                 → "178"
{{age}}                    → "45"
{{sprache}}                → "Deutsch" (konfigurierbar per Prompt)
```

**Zeitraum:**
```
{{zeitraum_7d}}            → "letzte 7 Tage"
{{zeitraum_30d}}           → "letzte 30 Tage"
{{zeitraum_90d}}           → "letzte 90 Tage"
{{datum_heute}}            → "20. März 2026"
```

**Pipeline (intern):**
```
{{stage1_body}}            → JSON-Summary Körper (Pipeline-Stufe 1)
{{stage1_nutrition}}       → JSON-Summary Ernährung
{{stage1_activity}}        → JSON-Summary Training
{{stage1_sleep}}           → JSON-Summary Schlaf (neu)
{{stage1_vitals}}          → JSON-Summary Vitalwerte (neu)
```

---

## 4. Pipeline-Konfiguration

### 4.1 Was ist eine Pipeline-Konfiguration?

Eine Pipeline-Konfiguration definiert:
- **Name** – z.B. "Alltags-Check", "Wettkampf-Analyse", "Schlaf-Fokus"
- **Aktive Module** – welche Datenquellen fließen ein (Körper, Ernährung, Training, Schlaf, Vitalwerte, Mentales)
- **Zeitraum je Modul** – z.B. Körper 30 Tage, Schlaf 7 Tage, Training 14 Tage
- **Stufen** – welcher Prompt wird in welcher Stufe verwendet
- **Standard** – eine Konfiguration kann als Standard markiert werden

### 4.2 Pipeline-Stufen

**Stufe 1 (parallel):** Mehrere Module-Prompts laufen gleichzeitig, jeder gibt ein JSON-Summary zurück

**Stufe 2:** Synthese-Prompt kombiniert alle Stage-1-Summaries zu einer narrativen Analyse

**Stufe 3 (optional):** Ziel-Abgleich oder spezifische Zusatzanalyse

Admin kann:
- Anzahl der Stufen festlegen (min. 2, max. 4)
- Jeden Stufen-Prompt zuweisen
- Module für Stufe 1 aktivieren/deaktivieren

### 4.3 Vordefinierte Konfigurationen (Beispiele)

**Alltags-Check (Standard):**
- Module: Körper (30T), Ernährung (30T), Training (14T)
- Stufe 1: pipeline_body + pipeline_nutrition + pipeline_activity
- Stufe 2: pipeline_synthesis
- Stufe 3: pipeline_goals

**Schlaf-Fokus:**
- Module: Schlaf (14T), Vitalwerte (7T), Training (14T)
- Stufe 1: pipeline_sleep + pipeline_vitals + pipeline_activity
- Stufe 2: pipeline_synthesis_sleep

**Wettkampf-Analyse:**
- Module: Körper (90T), Training (90T), Vitalwerte (30T), Ziele
- Stufe 1: alle Körper/Training/Vital-Module
- Stufe 2: pipeline_synthesis_performance

---

## 5. Nutzer-Ansicht: KI-Analyse starten

### 5.1 Einzelanalyse

1. Nutzer wählt Prompt aus der Bibliothek (nach Kategorie gefiltert)
2. KI-Analyse startet sofort
3. Ergebnis wird angezeigt und gespeichert

### 5.2 Pipeline

1. Nutzer wählt Pipeline-Konfiguration
2. Pipeline startet sofort (alle Stufen laufen automatisch)
3. Ergebnis wird angezeigt und gespeichert

### 5.3 Kein Konfigurationsschritt für Nutzer

Der Nutzer wählt nur Prompt oder Pipeline – kein weiterer Konfigurationsschritt.
Zeitraum und Module sind durch Admin in der Pipeline-Konfiguration festgelegt.

---

## 6. Analyse-Ergebnisse verwalten

### 6.1 Kategorie-Zuordnung

Jedes gespeicherte Analyse-Ergebnis erbt die Kategorie des ausgeführten Prompts.
Ermöglicht spätere Filterung nach Kategorie.

### 6.2 Filtern nach Kategorie

Im Analyse-Verlauf kann nach Kategorie gefiltert werden:
- "Alle" / "Körper" / "Ernährung" / "Training" / etc.

### 6.3 Analyse-Verlauf pro Prompt

Für jeden Prompt ist ein Verlauf einsehbar:
- Liste aller bisherigen Analysen mit diesem Prompt (Datum + Kurzauszug)
- Zeigt wie sich die KI-Aussage über Zeit verändert hat

### 6.4 Favoriten

Nutzer kann Analysen als Favorit markieren (Stern-Symbol).
Favoriten sind in der Verlaufs-Ansicht filterbar.

### 6.5 Löschen

Nutzer kann einzelne Analyse-Ergebnisse manuell löschen.
Keine Massen-Löschung (außer Admin).

---

## 7. Sprache

Die Ausgabesprache wird im Prompt-Template selbst gesteuert über den
Platzhalter `{{sprache}}`. Der Wert wird aus den Profil-Einstellungen gezogen.

**Mögliche Werte:** "Deutsch", "Englisch", "Französisch" (erweiterbar)

**Standard:** "Deutsch"

Kein separater Sprach-Schalter auf der Analyse-Seite – Sprache wird einmalig
im Profil konfiguriert.

---

## 8. Abgrenzung & offene Fragen

### In diesem Modul enthalten:
- Prompt-Bibliothek mit 8 Kategorien
- Vollständige Admin-Verwaltung (CRUD, Reihenfolge, Reset)
- Platzhalter-Browser mit Beispielwerten und Vorschau
- Pipeline-Konfigurationen (mehrere, speicherbar)
- Analyse-Ergebnisse: Kategorie, Filter, Verlauf, Favoriten, Löschen
- Sprach-Platzhalter

### Nicht in diesem Modul:
- Community-Prompts / Prompt-Import von extern → später
- KI-gestützte Prompt-Optimierung → später
- Automatisch geplante Analysen (z.B. wöchentlich) → später
- Prompts für noch nicht implementierte Module (Schlaf, Mentales) werden
  vorbereitet aber haben keine echten Daten bis die Module existieren

### Offene Fragen für technische Planung:
1. Wie werden Pipeline-Konfigurationen gespeichert? (neue DB-Tabelle oder JSON in ai_prompts?)
2. Platzhalter-Definitionen: statisch im Code oder dynamisch in DB (für zukünftige Erweiterung)?
3. Wie wird der Beispielwert für den Platzhalter-Browser berechnet – gleicher Endpunkt wie die echte Analyse?
4. Reihenfolge der Prompts: getrennte sort_order pro Kategorie oder global?

---

## 9. Trainingstypen & Fähigkeiten-Mapping (v9d → v9f Integration)

### 9.1 Hintergrund

In v9d wurde die Basis geschaffen:
- `training_types` Tabelle mit `abilities` JSONB-Spalte
- Admin-CRUD für Trainingstypen (ohne Abilities-UI)
- Taxonomie-Endpoint: `/api/admin/training-types/taxonomy/abilities`
- 5 Fähigkeiten-Dimensionen definiert:
  - 🎯 **Koordinativ:** Orientierung, Differenzierung, Kopplung, Gleichgewicht, Rhythmus, Reaktion, Umstellung
  - 💪 **Konditionell:** Kraft, Ausdauer, Schnelligkeit, Flexibilität
  - 🧠 **Kognitiv:** Konzentration, Aufmerksamkeit, Wahrnehmung, Entscheidungsfindung
  - 🎭 **Psychisch:** Motivation, Willenskraft, Stressresistenz, Selbstvertrauen
  - ♟️ **Taktisch:** Timing, Strategie, Antizipation, Situationsanalyse

### 9.2 Was wird in v9f ergänzt?

**Admin-UI: Fähigkeiten-Matrix**

Im AdminTrainingTypesPage Formular wird eine Fähigkeiten-Matrix hinzugefügt:
- 5 Sections (eine pro Dimension)
- Pro Dimension: Checkboxes für alle Fähigkeiten
- Multi-Select: Ein Trainingstyp kann mehrere Fähigkeiten pro Dimension trainieren
- Beispiel: "Kampfsport-Sparring" trainiert:
  - Koordinativ: Orientierung, Reaktion, Umstellung
  - Konditionell: Schnelligkeit, Ausdauer
  - Kognitiv: Entscheidung, Wahrnehmung
  - Psychisch: Stressresistenz, Selbstvertrauen
  - Taktisch: Timing, Antizipation

**Gespeichert als JSONB:**
```json
{
  "koordinativ": ["orientierung", "reaktion", "umstellung"],
  "konditionell": ["schnelligkeit", "ausdauer"],
  "kognitiv": ["entscheidung", "wahrnehmung"],
  "psychisch": ["stressresistenz", "selbstvertrauen"],
  "taktisch": ["timing", "antizipation"]
}
```

**Backend: Fähigkeiten-Aggregation**

Neue Endpoint-Funktion (oder Platzhalter-Funktion):
```python
def calculate_abilities_summary(profile_id, days=14):
    """
    Aggregiert trainierte Fähigkeiten über Zeitraum.

    Returns:
    {
      "total_activities": 14,
      "koordinativ": {
        "orientierung": 3,      # 3 von 14 Trainings
        "gleichgewicht": 5,
        ...
      },
      "konditionell": {
        "kraft": 8,
        "ausdauer": 4,
        ...
      },
      ...
      "balance_score": 0.67,    # 0-1, wie ausgewogen
      "top_dimension": "konditionell",
      "weak_dimension": "kognitiv"
    }
    """
```

**KI-Prompt Integration:**

Die Fähigkeiten-Platzhalter werden befüllt mit aggregierten Daten:
- `{{faehigkeiten_analyse}}` → vollständige Aufschlüsselung
- `{{faehigkeiten_koordinativ}}` → nur koordinative Dimension
- etc.

Pipeline-Prompt "Training" erhält zusätzlichen Context:
```
Analyse die Fähigkeitenverteilung:
{{faehigkeiten_analyse}}

Gib Empfehlungen für untertrainierte Bereiche.
```

### 9.3 Nutzen für KI-Analyse

**Beispiel-Insight:**
> "Deine letzten 14 Trainings fokussieren stark auf **konditionelle Fähigkeiten** (Kraft: 8×, Ausdauer: 4×). Koordinative Fähigkeiten kommen zu kurz (nur 3× Gleichgewicht, 2× Reaktion). Für einen ausgewogenen Trainingsplan empfehle ich 2-3 koordinationslastige Einheiten pro Woche – z.B. Kampfsport-Techniktraining, Balance-Übungen oder Mobility-Routinen mit Fokus auf Bewegungskontrolle."

**Korrelationen:**
- Verletzungen / Überlastung ↔ Koordinations-Defizit
- Plateaus im Krafttraining ↔ fehlende kognitive/taktische Komponente
- Erholungsprobleme ↔ psychische Fähigkeiten untertrainiert

### 9.4 Implementierungs-Reihenfolge

1. ✅ v9d Phase 1b: DB-Schema + Admin-CRUD (ohne Abilities-UI) → **erledigt**
2. 🔲 v9f: Abilities-Matrix UI im Admin-Formular
3. 🔲 v9f: Backend-Funktion `calculate_abilities_summary()`
4. 🔲 v9f: Platzhalter `{{faehigkeiten_*}}` implementieren
5. 🔲 v9f: Standard-Prompts aktualisieren mit Fähigkeiten-Context
6. 🔲 v9f: Admin-Doku: "Best Practices" für Fähigkeiten-Zuordnung

---

EOF
echo "OK"