# Progressionsgraph — KI-Planung (Ist-Stand)

**Stand:** 2026-05-22 (Dokumentation) · **App-Version:** **0.8.218** · **DB:** Migration **088**  
**Maßgeblich für Code:** `backend/version.py` (`APP_VERSION`, `DB_SCHEMA_VERSION`)

> **Diese Datei ist die zentrale Referenz** für die KI-gestützte Planung im Progressionsgraph.  
> Ältere Abschnitte in `HANDOVER.md` §2.8 und `PLANNING_KI_ROADMAP.md` verweisen hierher.

**Bezüge:**  
`.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md` (Zielarchitektur) ·  
`.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md` (Retrieval/Scoring) ·  
`.claude/docs/technical/SKILL_SCORING_SPEC.md` (Fähigkeiten-Scoring) ·  
`docs/architecture/PLANNING_KI_ROADMAP.md` (Produkt-Roadmap Phase G+)

---

## 1. Fachliche Abgrenzung

| Thema | Progressionsgraph (dieses Feature) | Trainingsplanung (Phase G, später) |
|--------|-------------------------------------|-------------------------------------|
| Ziel | Curriculum / Technikpfad über Übungen | Konkrete Trainingseinheit für Gruppe |
| Kontext | Zieltext, Start/Ziel, Roadmap, optional Graph-Kanten | Gruppe, Historie, Termin, Rahmen |
| Pipeline | `planning_progression_roadmap.py` → Path-Builder | Eigene Pipeline (noch offen) |
| Gruppenanalyse | **Nein** | **Ja** |
| Wiederverwendung | `planning_skill_expectations.py`, `planning_exercise_form_context.py` | Gleiche Bausteine, andere Scopes |

**Shinkan-Regel:** Der Progressionsgraph ist **keine** persönliche Tracking-App und plant **nicht** für einzelne Sportler.

---

## 2. Trainer-Workflow (UI)

Aktuell in `ExerciseProgressionPathBuilder.jsx` (eingebettet in `ExerciseProgressionGraphPanel.jsx`):

```
① Ziel eingeben (+ optional Start/Ziel-Felder manuell)
② „Start/Ziel analysieren“ (optional, start_target_only)
③ „Roadmap vorschlagen“ (roadmap_only, LLM-Roadmap)
④ Roadmap bearbeiten (Major Steps + Stufen-Details)
⑤ „Übungen matchen“ (roadmap_first + roadmap_override)
⑥ Lücken mit KI schließen (gap_fill_offers + Vorbereitungs-Dialog)
⑦ „Pfad in Graph speichern“ (Sequenz-Kanten)
```

**Bekannte UX-Schuld:** Alle Schritte liegen auf **einer langen Scroll-Seite** — Überarbeitung als Wizard/Stepper ist geplant (separater UI-Chat). Briefing-Vorlage siehe unten §10.

---

## 3. Architektur (Module)

```mermaid
flowchart TB
    subgraph ui [Frontend]
        EPB[ExerciseProgressionPathBuilder]
        GFM[ExerciseGapFillPrepModal]
        PCtx[planningContextForExerciseAi.js]
    end

    subgraph api [API]
        PPS[POST /api/planning/progression-path-suggest]
        EAI[POST /api/exercises/ai/suggest]
        SEQ[POST /api/exercise-progression-graphs/:id/edges/sequence]
        PUT[PUT /api/exercise-progression-graphs/:id]
    end

    subgraph roadmap [Roadmap-Pipeline]
        PR[planning_progression_roadmap.py]
        ST087[Prompt 087 start_target]
        ST078[Prompts 078/079 roadmap + stage_spec]
    end

    subgraph match [Match + QA]
        PB[planning_exercise_path_builder.py]
        RET[planning_exercise_retrieval.py]
        PG[planning_exercise_progression.py]
        SEM[planning_exercise_semantics.py]
    end

    subgraph skills [Fähigkeiten — wiederverwendbar]
        PSE[planning_skill_expectations.py]
        PEFC[planning_exercise_form_context.py]
        AIF[planning_exercise_path_ai_fill.py]
    end

    subgraph persist [Persistenz Graph]
        G088[(planning_roadmap JSONB — Migration 088)]
        EDGES[(exercise_progression_edges)]
    end

    EPB --> PPS
    EPB --> SEQ
    EPB --> PUT
    GFM --> EAI
    PPS --> PR
    PPS --> PB
    PB --> RET
    PB --> PG
    PB --> PSE
    AIF --> PEFC
    PSE --> RET
    SEQ --> EDGES
    PUT --> G088
    SEQ --> G088
```

### 3.1 Verantwortlichkeiten

| Modul | Aufgabe |
|--------|---------|
| `planning_progression_roadmap.py` | Phasen A–C: Zielanalyse, Roadmap, `stage_specs`; Start/Ziel-Auflösung (Trainer > KI > Regex) |
| `planning_exercise_path_builder.py` | `suggest_progression_path`: roadmap_first Match, QA, Gap-Offers |
| `planning_exercise_progression.py` | Graph auflösen, Nachfolger-Kanten für Retrieval-Bias |
| `planning_skill_expectations.py` | Skill-Erwartungen pro Scope (`progression_stage`, `progression_path`, später `training_section`) |
| `planning_exercise_form_context.py` | `planning_context` / Gap-Snapshot für Übungs-KI |
| `planning_exercise_path_ai_fill.py` | Gap-Fill-Angebote, `goal_for_ai`, `context_preview` |
| `progression_graph_planning_artifact.py` | Validierung `planning_roadmap` JSON (Schema v1, max. 64 KB) |

---

## 4. API — `POST /api/planning/progression-path-suggest`

### 4.1 Wichtige Request-Flags

| Feld | Typ | Bedeutung |
|------|-----|-----------|
| `query` | string | Ziel / Entwicklungsrichtung (min. 3 Zeichen) |
| `max_steps` | int | Anzahl Major Steps (2–10) |
| `progression_graph_id` | int? | Gewählter Graph — siehe §5 |
| `roadmap_first` | bool | Match pro `stage_spec` statt iterativem Pfad |
| `roadmap_only` | bool | Nur Roadmap, keine Übungen |
| `start_target_only` | bool | Nur Start/Ziel-Analyse |
| `roadmap_override` | object | Trainer-bearbeitete `major_steps` + `stage_specs` |
| `start_situation`, `target_state`, `roadmap_notes` | string? | Strukturierte Eingabe (Priorität vor KI) |
| `include_llm_start_target` | bool | LLM-Extraktion Start/Ziel (Prompt **087**) |
| `include_llm_roadmap` | bool | LLM Roadmap (Prompts **078/079**) |
| `include_llm_intent` | bool | LLM Intent für Semantic Brief (Roadmap-Vorschlag: **true** seit 0.8.217) |
| `include_path_qa`, `include_ai_gap_fill` | bool | QS, Lücken-Angebote |

### 4.2 Wichtige Response-Felder

| Feld | Bedeutung |
|------|-----------|
| `progression_roadmap` | Artefakte A/B/C inkl. `resolved_structured`, `stage_specs`, `prompt_slugs` |
| `steps[]` | Gematchte Übungen; pro Schritt u. a. `roadmap_*`, `skill_expectations` |
| `path_skill_expectations` | Pfadweite Skill-Erwartungen |
| `gap_fill_offers[]` | Lücken mit `context_preview`, `goal_for_ai` |
| `path_qa` | QS inkl. `roadmap_qa_mode: roadmap_first_lite` |

### 4.3 Prompt-Slugs (nur in `ai_prompts`, nie Hardcoding)

| Slug | Migration | Phase |
|------|-----------|-------|
| `planning_progression_start_target` | **087** | Start/Ziel-Extraktion |
| `planning_progression_goal_analysis` | **078** | Zielanalyse |
| `planning_progression_roadmap` | **078** | Roadmap (micro → major) |
| `planning_progression_stage_spec` | **079** | Stufenspezifikation |

---

## 5. Roadmap-Match — Stufen-Qualität (0.8.218)

Pro Major Step gilt:

1. **Stufen-Brief** — `semantic_brief_for_stage()` ergänzt `must_phrases` um das Stufen-Lernziel.
2. **Stufen-Gate** — `exercise_passes_stage_learning_goal_gate()` prüft Lernziel-Text in Titel/Summary/Ziel oder Mindest-`semantic_score`.
3. **Kein Fallback** — Bei `roadmap_first` wird **nicht** auf die globale `goal_query` zurückgefallen; passt keine Übung → **Lücke** (`roadmap_unfilled`) statt themenfremder Übung.
4. **Retrieval** — Bonus/Strafe im Hybrid-Score je nach Stufen-Passung.
5. **QS** — `detect_off_topic_steps` erkennt `stage_mismatch` anhand `roadmap_learning_goal`.

Tests: `test_planning_roadmap_stage_match.py`

---

## 6. Rolle des bestehenden Graphs

**Wichtig — häufiges Missverständnis:**

| Aspekt | Verhalten |
|--------|-----------|
| **KI-Pfadvorschlag** | Baut einen **neuen** Übungspfad aus der **Bibliothek** (Roadmap-first), nicht aus vorhandenen Graph-Knoten als Start |
| **Schritt 1** | Kein Anker → **kein** Graph-Bias |
| **Ab Schritt 2** | Anker = vorherige Übung im Vorschlag → ausgehende Kanten im Graph werden geladen |
| **Scoring** | Nachfolger im Graph: Bonus `progression` (ca. **4–10 %** Gewicht, Semantik/Profil dominieren) |
| **Speichern** | `POST …/edges/sequence` **fügt Kanten hinzu** — ersetzt den Graph nicht |
| **Nicht implementiert** | „Ab letztem Graph-Knoten erweitern“, bestehende Sequenz als Pfad-Start |

Code: `planning_exercise_progression.py` → `apply_progression_context_to_pack` → `planning_exercise_retrieval.py` (`prog_hit`).

---

## 7. Persistenz

### 6.1 Kanten (`exercise_progression_edges`)

- Übungsfolge als gerichtete Kanten `next_exercise`
- Varianten-aware (Migration **034**)
- Kanten-Notizen aus Pfad-Begründungen oder Fallback-`segment_notes`

### 6.2 Planungs-Artefakt (`planning_roadmap` JSONB, Migration **088**)

Gespeichert am **Graph-Container** (`exercise_progression_graphs`), Schema v1:

```json
{
  "schema_version": 1,
  "goal_query": "…",
  "start_situation": "…",
  "target_state": "…",
  "roadmap_notes": "…",
  "max_steps": 5,
  "progression_roadmap": { },
  "path_skill_expectations": { }
}
```

| Aktion | API |
|--------|-----|
| Speichern (Roadmap/Match) | `PUT /api/exercise-progression-graphs/:id` |
| Speichern (mit Pfad) | `POST …/edges/sequence` (optional `planning_roadmap` im Body) |
| Laden | `GET /api/exercise-progression-graphs/:id` → Frontend stellt Workflow-Felder wieder her |

Validierung: `progression_graph_planning_artifact.py` · Tests: `test_progression_graph_planning_artifact.py`

**`planning_roadmap` ≠ Graph-Kanten:** Metadaten für Wiederaufnahme der KI-Planung, nicht der Übungsgraph selbst.

---

## 8. Planungs-Intent (gemeinsam mit Trainingsplanung)

Modul: **`planning_intent_context.py`** — domänenneutral, wiederverwendbar in Phase G.

| Baustein | Progressionsgraph heute | Trainingsplanung (Phase G) |
|----------|-------------------------|----------------------------|
| `build_planning_intent_context` | Aus `goal_query`, Zielanalyse, Notizen | Aus `section_guidance`, Slot, Einheit |
| `explicit_exclusions` | Negationen (`ohne/kein/nicht …`) | gleich |
| `path_anti_patterns` | → jede `stage_spec.anti_patterns` | → Abschnitts-/Slot-Brief |
| `path_success_criteria` | → `success_criteria` + Matching | → Slot-Erwartung |
| `finalize_stage_specs_with_intent` | Nach heuristischer/LLM-Roadmap | Analog für Sektionen |

LLM: Migration **089** — Prompts `planning_progression_goal_analysis` + `planning_progression_stage_spec` erhalten `intent_context_json`; Ausschlüsse nicht erfinden, nur aus Anfrage übernehmen.

Matching: `anti_patterns` + `success_criteria` → `build_stage_match_brief` → Retrieval-Gate (Titel + Summary + Goal).

## 9. Fähigkeiten-Scoring-Anbindung

Modul: `planning_skill_expectations.py`

| Scope | Verwendung heute | Phase G (vorbereitet) |
|-------|------------------|------------------------|
| `progression_path` | Einmaliges Pfad-Profil (`path_skill_expectations`) | — |
| `progression_stage` | Pro Roadmap-Stufe vor Retrieval + in Gap-Kontext | — |
| `training_section` | — | Trainingsabschnitt |
| `framework_slot` | — | Rahmen-Slot |

Quellen: `semantic_topic`, `text_match`, `load_profile` (aus `stage_spec`).

Integration:
- Retrieval: `apply_expectations_to_target` → Hybrid-Score
- UI: Tags pro Pfadschritt + Pfad-Header; Gap-Kontext „Erwartete Fähigkeiten“
- KI-Neuanlage: `expected_skills` in `context_preview` / `goal_for_ai`

---

## 10. KI-Lücken (Gap-Fill)

Flow:
1. `roadmap_unfilled` / QA-Lücken → `gap_fill_offers`
2. Trainer: **„Vorbereiten & KI anlegen“** → `ExerciseGapFillPrepModal` (Titel, Stufen-Lernziel, Ergänzungen)
3. `POST /api/exercises/ai/suggest` mit `planning_context`
4. Vorschau → Übung anlegen → in Pfad einfügen

Kontext-Helfer: `frontend/src/utils/planningContextForExerciseAi.js`

---

## 11. Implementierungsstände (Phasen)

| Phase | Inhalt | Status | Version |
|-------|--------|--------|---------|
| F0–F2 | Roadmap-Pipeline + LLM-Prompts 078/079 | ✅ | 0.8.204–205 |
| F3 | `roadmap_first` Match pro Stufe | ✅ | 0.8.206–209 |
| F4 | Roadmap-Review UI + `roadmap_override` | ✅ | 0.8.207 |
| F5 | Start/Ziel strukturiert + LLM **087** + Zwei-Schritt-UI | ✅ | 0.8.210–214 |
| F6 | Gap-Prep-Modal + reicher `planning_context` | ✅ | 0.8.212–214 |
| F7 | `planning_skill_expectations` (Retrieval + UI + Gap) | ✅ | 0.8.215–216 |
| F8 | Editierbare `stage_specs` in UI | ✅ | 0.8.216 |
| F9 | `planning_roadmap` Persistenz (Migration **088**) | ✅ | 0.8.217 |
| F10 | Stufen-Lernziel-Gate beim Match (kein goal_query-Fallback) | ✅ | 0.8.218 |
| **G** | Trainingsplanung eigene Pipeline + Graph-Referenz | 🔲 | — |
| **UX** | Wizard/Stepper statt Scroll-Monolith | 🔲 | separater Chat |

---

## 12. Offenes Backlog (priorisiert)

1. **UI-Überarbeitung** — Wizard mit 4 Schritten, progressive disclosure (Briefing unten)
2. **Graph-Erweiterungsmodus** — Start ab gewähltem Knoten / letzter Sequenz
3. **Kontext auf allen Pfad-Schritten** in UI (nicht nur Lücken)
4. **Trainingsplanung Phase G** — Pipeline mit Gruppenkontext, Wiederverwendung `planning_skill_expectations`
5. Enrichment / Prompt-Feintuning
6. Mitai Workflow-Engine (langfristig)

### Briefing-Vorlage UI-Chat (Copy-Paste)

Siehe Nutzer-Chat 2026-05-22 oder `HANDOVER.md` §2.8 — Abschnitt „UI-Überarbeitung“.

Kern: Wizard ① Ziel & Start/Ziel → ② Roadmap → ③ Match → ④ Lücken & Speichern; Backend-Pipeline unverändert lassen.

---

## 13. Tests

| Datei | Abdeckung |
|-------|-----------|
| `test_planning_progression_roadmap.py` | Roadmap-Pipeline, Override, Start/Ziel |
| `test_planning_exercise_path_builder.py` | Pfad-Annotierung, Skill-Expectations auf Steps |
| `test_planning_skill_expectations.py` | Skill-Erwartungen, Scopes |
| `test_planning_intent_context.py` | Intent-Kontext, finalize stage_specs |
| `test_planning_exercise_path_ai_fill.py` | Gap-Fill, `expected_skills` in goal text |
| `test_planning_exercise_form_context.py` | `planning_context`, Gap-Snapshot |
| `test_progression_graph_planning_artifact.py` | JSONB-Artefakt-Validierung |
| `test_planning_exercise_progression.py` | Graph-Auflösung, Nachfolger |

---

## 14. Dokumenten-Index (Drift vermeiden)

| Frage | Primäre Quelle |
|-------|----------------|
| Was ist der aktuelle Ist-Stand? | **Diese Datei** |
| Zielarchitektur / JSON-Artefakte | `PLANNING_PROGRESSION_ROADMAP_SPEC.md` |
| Retrieval, Hybrid-Score, Intents | `PLANNING_EXERCISE_SUGGEST_CONTEXT.md` |
| Produkt-Roadmap Phase G+ | `PLANNING_KI_ROADMAP.md` |
| Session-Handover / nächste Schritte | `docs/HANDOVER.md` §2.8 |
| Fähigkeiten-Scoring allgemein | `SKILL_SCORING_SPEC.md` |
| Versionen / Changelog | `backend/version.py` |

**Pflege-Regel:** Bei jeder abgeschlossenen Teilphase diese Datei + `HANDOVER.md` §2.8 + `version.py` CHANGELOG aktualisieren.

---

## 15. Changelog (Dokument)

| Datum | Änderung |
|-------|----------|
| 2026-05-22 | Erstfassung Ist-Stand 0.8.217 — zentrale Referenz nach F5–F9 |