shinkan-jinkendo/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md

# Progressionsgraph — KI-Planung (Ist-Stand)

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

> **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) ·  
**`PLANNING_CATALOG_PROMPT_SNIPPETS.md`** (H1 — modulare Katalog-Prompts) ·  
`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)

**Primär:** `ProgressionGraphEditor.jsx` (integrierter Slot-Editor, Phase B).  
**Legacy/Parallel:** `ExerciseProgressionPathBuilder.jsx` (Scroll-Monolith — gleiche API, Katalog-Kontext-Dropdowns dort noch nachziehen).

```
① Ziel eingeben (+ Planungskontext: Primärfokus, Stil, Trainingsstil, Zielgruppe)
② Optional: Start/Ziel-Felder manuell oder „Start/Ziel analysieren“
③ „Roadmap generieren“ (roadmap_only, LLM-Roadmap)
④ Roadmap bearbeiten (Major Steps + Stufen-Details)
⑤ „Übungen matchen“ (roadmap_first + roadmap_override + Auto-QS/Rematch)
⑥ Lücken: KI-Angebote → „KI anlegen“ (Gap-Prep-Modal) → in Slot
⑦ „Graph speichern“ (planning_roadmap + optional Kanten-Sequenz)
```

**Bekannte UX-Schuld:** PathBuilder = lange Scroll-Seite; GraphEditor = kompakter, aber noch kein Wizard. Stepper geplant (separater UI-Chat). Briefing §12.

---

## 3. Architektur (Module)

```mermaid
flowchart TB
    subgraph ui [Frontend]
        PGE[ProgressionGraphEditor]
        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]
        PCC[planning_catalog_context.py]
        REM[planning_path_rematch.py]
        REF[planning_path_refine_stage.py]
        QAP[planning_path_qa_pipeline.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
    PGE --> PPS
    PGE --> SEQ
    PGE --> PUT
    GFM --> EAI
    PPS --> PR
    PPS --> PB
    PB --> PCC
    PB --> REM
    PB --> REF
    PB --> QAP
    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, Auto-QS, Rematch, Gap-Offers |
| `planning_catalog_context.py` | **Expliziter Katalog-Kontext** (Fokus, Stil, Trainingsstil, Zielgruppe) → `PlanningTargetProfile` |
| `planning_path_rematch.py` | Auto-Rematch betroffener Slots (`max_rematch_rounds`) |
| `planning_path_refine_stage.py` | Stufen-Spec-Verfeinerung bei `stage_mismatch` (Phase C) |
| `planning_path_qa_pipeline.py` | Mehrstufige QS → `optimization_hints` |
| `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) |
| `planning_exercise_profiles.py` | **Katalog-Scoring** (Fokus/Stil/TT/ZG/Skills) — gemeinsam mit Einheitsplanung |
| `planning_exercise_target_pipeline.py` | Query-Intent-Pipeline — Progressionsgraph nutzt `query_only`-Modus + Katalog-Overlay |

---

## 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) |
| `planning_catalog_context` | object? | Primärfokus, Stilrichtung, Trainingsstil, Zielgruppe (IDs + `is_primary`) |
| `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 |
| `auto_rematch_after_qa` | bool | Auto-Rematch nach QS (Default **true**) |
| `auto_refine_stage_spec` | bool | Stufen-Spec bei `stage_mismatch` schärfen (Default **true**) |
| `max_rematch_rounds` | int | Rematch-Runden 0–4 (Default **3**) |
| `include_path_qa`, `include_llm_path_qa`, `include_ai_gap_fill` | bool | QS, LLM-Ganzpfad, 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. `qa_tiers`, `optimization_hints`, `rematch_log`, `refine_log` |
| `target_profile_summary` | Erwartungsprofil inkl. Katalog-Dimensionen (nach Match) |
| `match_summary` | `library_matches`, `gap_fill_offer_count`, `roadmap_unfilled_count` |

---

## 4.4 Planungskontext — Katalog vs. Technik-Vokabular

Shinkan unterscheidet **drei Schichten** (kein monolithisches „Vokabular“):

| Schicht | Was | Wo | Beispiel |
|---------|-----|-----|----------|
| **Katalog-Dimensionen** | Was für Training? | DB: `focus_areas`, `style_directions`, `training_types`, `target_groups`, `skills` | Gewaltschutz, Breitensport, Shotokan |
| **Disambiguierung (Technik)** | Verwechslungs-Nachbarn | Code: `planning_exercise_semantics.py` (`_GERI_TECHNIQUES`, …) | Mae Geri ≠ Mawashi Geri |
| **Didaktik / Kausalität** | Reihenfolge, Lernphasen | Roadmap + LLM Pfad-QS | Grundlagen vor Geschwindigkeit |

**Seit 0.8.233:** `planning_catalog_context` im Request und im Graph-Artefakt (`planning_catalog_context` JSON). Fließt in `PlanningTargetProfile` → Hybrid-Retrieval (`score_exercise_against_target`: „Fokusbereich passend“, …). Zusätzlich additive Text-Signale aus Anfrage + Start/Ziel + Notizen (`planning_exercise_text_signals`).

**Geplant (H1):** dieselben Dimensionen als **kaskadierte Prompt-Snippets** in Roadmap-, Stufen-Spec- und Pfad-QS-Prompts — Priorität Primärfokus → Trainingsstil → Zielgruppe → Stilrichtung — siehe **`PLANNING_CATALOG_PROMPT_SNIPPETS.md`**.

**Technik-Gates** (`technique_scope`, Geschwister-Ausschluss) nur bei `topic_type == "technique"` — Fokus-Pfade (Gewaltschutz, Fitness, …) werden nicht wie Mae-Geri-Pfade behandelt.

Fallback: fehlt `planning_catalog_context` im Request, wird aus gespeichertem `planning_roadmap` am Graph geladen.

### 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–0.8.233)

Pro Major Step gilt:

1. **Stufen-Brief** — `build_stage_match_brief()` aus Lernziel, `anti_patterns`, Erfolgskriterien, Pfad-Kontext.
2. **Stufen-Gate** — `exercise_passes_stage_fit()` / `exercise_passes_stage_learning_goal_gate()` auf vollem Übungstext.
3. **Kein blindes Rank-Fallback** — ohne Gate-Passung → `roadmap_unfilled`, nicht themenfremde Übung.
4. **Post-Match-Gate** — `_roadmap_step_passes_post_match_gate()` = gleiche QS wie `detect_off_topic_steps` (kein Rematch-Treffer, der sofort wieder `stage_mismatch` wäre).
5. **Retrieval** — Hybrid-Score: Volltext + Semantik + **Profil/Katalog** + Skill-Erwartungen + optional Graph-Bias.
6. **Auto-Optimierung (ein Match-Lauf):**
   - **Phase B:** Rematch-Schleife (`planning_path_rematch.py`) für `rematch_slot` / `roadmap_unfilled`
   - **Phase C:** `planning_path_refine_stage.py` — `anti_patterns` / Erfolgskriterien aus QS
   - Purge persistent `stage_mismatch` → Slot leeren + KI-Gap
   - LLM Pfad-QS **nach** Rematch auf finalem Pfad
   - Gap-Offers für alle leeren Slots **vor** `path_qa`-Summary

Tests: `test_planning_roadmap_stage_match.py`, `test_planning_path_rematch.py`, `test_planning_path_refine_stage.py`, `test_planning_catalog_context.py`

### Referenz-Validierung (Mae Geri, 2026-05)

| Phase | Pfad-QS | Ergebnis |
|-------|---------|----------|
| Vor Roadmap/KI-Anpassung | ~65 % | Strukturelle Lücken (Grundlagen, Reihenfolge, Zielgenauigkeit) |
| Nach Trainer-Roadmap + KI-Angebote in leeren Slots | **~88 % OK** | Vollständige Curriculum-Abdeckung; positive LLM-Empfehlungen |

**Lesson:** Workbench + Katalog-Kontext + Roadmap sind der Hebel; Technik-Hardcoding allein reicht nicht für Didaktik.

---

## 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": { },
  "planning_catalog_context": {
    "focus_areas": [{ "id": 1, "is_primary": true }],
    "style_directions": [],
    "training_types": [{ "id": 2, "is_primary": true }],
    "target_groups": []
  },
  "slot_contents": [ ],
  "last_findings": { }
}
```

| 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).

### Stufen im Gesamtziel (`planning_stage_context.py`)

| Feld | Bedeutung |
|------|-----------|
| `start_state` | Soll-Start der Stufe (= `target_state` der Vorstufe / Pfad-Start) |
| `target_state` | Ziel nach dieser Stufe (= Soll für den nächsten Schritt) |
| `build_contextualized_stage_goal()` | Lernziel + Start + Stufen-Ziel + Gesamtziel → Brief/Retrieval |

Deterministisch: `derive_stage_specs_transition_states()` nach Roadmap-Pipeline; LLM kann Felder überschreiben (Prompt **090**).

### Mehrstufige Pfad-QS (`planning_path_qa_pipeline.py`)

| Stufe | Inhalt | Ableitung |
|-------|--------|-----------|
| **tier1** | Deterministische Gates (Technik-Scope, Ausschlüsse, unfilled) | `optimization_hints` → `rematch_slot`, `refine_stage_spec` |
| **tier2** | Übergangs-Lücken zwischen Schritten | `bridge_or_gap_fill` |
| **tier3** | LLM-Ganzpfad + Empfehlungen | `review_roadmap` |

API: `path_qa.qa_tiers`, `path_qa.optimization_hints` — **kein** anfrage-spezifischer Patch, sondern strukturierte Rückkopplung. Auto-Rematch-Schleife: Backlog (QS → Aktion → erneutes Match).

Phase G: gleiche Tiers für Abschnitts-QS nach Einheits-Match.

## 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 + kein goal_query-Fallback | ✅ | 0.8.218 |
| **F11** | Auto-Rematch + Stufen-Spec-Refine + mehrstufige QS | ✅ | 0.8.225–0.8.230 |
| **F12** | Post-Match-Gate, LLM-QA nach Rematch, Gap-Timing, `roadmap_unfilled`-Sync | ✅ | 0.8.231–0.8.232 |
| **F13** | **Katalog-Kontext** (`planning_catalog_context`) im Match + Graph-Artefakt | ✅ | **0.8.233** |
| **F14** | `ProgressionGraphEditor` Slot-UI + Planungskontext-Dropdowns | ✅ | 0.8.233 |
| **H1** | **Katalog-Prompt-Snippets** — modulare LLM-Anweisungen pro Dimension | 🔲 | Spec **`PLANNING_CATALOG_PROMPT_SNIPPETS.md`** |
| **G** | Trainingsplanung: eigene Pipeline + Wiederverwendung Bausteine (§16) | 🔲 | — |
| **UX** | Wizard/Stepper; PathBuilder-Parität Katalog | 🔲 | — |
| **H** | Technik-Disambiguierung konfigurierbar (DB statt Code-Tuples) | 🔲 | Backlog |
| **D′** | Auto Gap-Fill (KI generiert bei persistent `roadmap_unfilled`) | 🔲 | Backlog |

---

## 12. Offenes Backlog (priorisiert)

1. **H1 Katalog-Prompt-Snippets** — modulare LLM-Anweisungen (Priorität: Primärfokus → Trainingsstil → Zielgruppe → Stilrichtung) — **`PLANNING_CATALOG_PROMPT_SNIPPETS.md`**
2. **Dev-Regression:** Gewaltschutz + Breitensport + Kinder (ohne Mae Geri) — Katalog-Match verifizieren
2. **PathBuilder-Parität** — gleiche `planning_catalog_context`-Dropdowns in `ExerciseProgressionPathBuilder`
3. **QS-UI** — positive LLM-Hinweise als „Highlights“, nicht als „Optimierungspotenziale“
4. **UI-Wizard** — 4 Schritte (Ziel → Roadmap → Match → Lücken); Backend unverändert
5. **Graph-Erweiterungsmodus** — Start ab gewähltem Knoten / letzter Sequenz
6. **Phase D′** — automatisches KI-Gap-Fill bei persistent leeren Slots
7. **Trainingsplanung Phase G** — siehe §16
8. **Technik-Katalog externalisieren** — konfigurierbare `concept_groups` (Backlog)
9. Graph-Metadaten: Primärfokus/Stil als Spalten (Reporting)
10. Mitai Workflow-Engine (langfristig)

### Briefing-Vorlage UI-Chat

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

---

## 16. Wiederverwendung in der Trainingsplanung (Phase G)

Die **komplexere Trainingsplanung** (Einheit, Rahmen-Slot, Abschnitt, parallele Streams) soll **keine zweite Retrieval-Welt** bauen, sondern bestehende Module mit **anderem Kontext-Pack** nutzen.

### 16.1 Was Progressionsgraph liefert (Workbench-Muster)

| Baustein | Progressionsgraph | Trainingsplanung (Ziel) |
|----------|-------------------|-------------------------|
| `PlanningTargetProfile` | Query + Katalog + Skills | Einheit + Abschnitt + Slot + Katalog + Historie |
| `planning_catalog_context` | Am Graph gespeichert | Pro Einheit / Slot / Trainer-Voreinstellung |
| `planning_skill_expectations` | `progression_stage` / `progression_path` | **`training_section`**, **`framework_slot`** |
| `planning_exercise_retrieval` | Roadmap-Stufen-Match | Abschnitts-Suche (`suggest_planning_exercises`) — **produktiv** |
| `planning_path_qa_pipeline` | Curriculum-QS | Abschnitts-QS (Kohärenz, Streams) |
| `planning_intent_context` | Pfad-Ausschlüsse → Stufen | Abschnitts-Guidance → Brief |
| `planning_exercise_form_context` | Pfad-Lücken | Abschnitts-/Slot-Lücken |
| Roadmap-Pipeline | Curriculum Major Steps | **Nicht 1:1** — Phasen/Streams + Vorlagen |
| Technik-Disambiguierung | bei `topic_type=technique` | nur bei explizitem Technik-Abschnitt |

### 16.2 Was Phase G neu braucht

- **Gruppen-/Historie-Kontext-Pack** (`AI_PLANNING_KI_MULTISTAGE_FORECAST` S0–S4)
- **Abschnitts-Didaktik** — Dauer, Parallel-Streams, Coaching (`training_unit_phases`)
- **Rahmen-Blueprint** — bereits `training_framework_programs` / Slot-Blueprints
- **Eigene Orchestrierung** pro Einheit — kein Curriculum über N Wochen

### 16.3 Integrations-Reihenfolge (Phase G)

1. **G0** — Katalog in Einheits-Editor → bestehende Suggest-Pipeline
2. **G1** — Scope `training_section` + Skill-Erwartungen aktiv
3. **G2** — Abschnitts-QS (Hint-Struktur wie Graph)
4. **G3** — Framework-Slot + Gap-Fill
5. **G4** — Gruppenkontext-Pack

**Nicht:** Roadmap-first-Loop 1:1 auf Trainingseinheit mappen.

Domänenbezug: **`DOMAIN_MODEL.md`** §1–2 (Katalog-Dimensionen).

---

## 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 |
| `test_planning_path_rematch.py` | Auto-Rematch, unfilled-Platzhalter |
| `test_planning_path_refine_stage.py` | Stufen-Spec-Refine |
| `test_planning_stage_anti_patterns.py` | Anti-Pattern-Sanitizer, Stufen-Gate |
| `test_planning_catalog_context.py` | Katalog-Kontext → Target-Profil |

---

## 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 |
| 2026-05-22 | F11–F14: Auto-Optimierung, Katalog-Kontext, GraphEditor, Mae-Geri-Validierung, Phase-G-Wiederverwendung §16 |