shinkan-jinkendo/docs/architecture/PLANNING_KI_ROADMAP.md

# Planungs-KI — Produkt-Roadmap

**Stand:** 2026-05-22  
**App-Version:** **0.8.233** — maßgeblich `backend/version.py`

Diese Roadmap ergänzt die **Architektur-Refaktor-Roadmap** (`UMSETZUNGSPLAN_ROADMAP.md`) und gilt **nur für KI-gestützte Trainingsplanungsunterstützung**.

**Ist-Stand Progressionsgraph (detailliert):** `PLANNING_PROGRESSION_GRAPH_KI.md`  
**Leit-Spec:** `.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md`

---

## Strategische Entscheidung (verbindlich)

1. **Progressionsgraph:** Planung **vom Ziel rückwärts** (Roadmap-first), nicht Bibliothek-first.  
2. **Keine Gruppenanalyse** im Graphen — Kontext = Zieltext, Katalog-Dimensionen, Start/Ziel, Roadmap, optional Graph-Kanten.  
3. **Drei Schichten statt monolithischem Vokabular:** Katalog (DB) · Technik-Disambiguierung (Code, nur bei Technik-Themen) · Didaktik (Roadmap + LLM-QS).  
4. **Trainingsplanung** (Einheit, Rahmen, Abschnitt): eigene Pipeline (Phase G), **mit** Gruppenkontext — siehe `AI_PLANNING_KI_MULTISTAGE_FORECAST.md` S0–S4 und Ist-Doku §16.  
5. **Orchestrierung:** Workflow-**lite** jetzt (`planning_progression_roadmap.py`, `planning_exercise_path_builder.py`); Mitai Workflow-Engine **später**, wenn Phase G stabil ist.

---

## Phasen-Übersicht

| Phase | Domäne | Kurzbeschreibung | Status |
|-------|--------|------------------|--------|
| P0–P2 | Übungssuche | Kontext-Pack, Hybrid-Score, LLM-Rerank | ✅ |
| A–C2 | Übungssuche | Voll-Library, Graph, Varianten | ✅ |
| C3 | Progressionsgraph | Pfad-Builder (retrieval-first) | ✅ |
| E–E3 | Progressionsgraph | Semantik, QA, Lücken-Angebote | ✅ |
| **F0–F4** | Progressionsgraph | Roadmap-Pipeline, LLM, roadmap_first, UI Review | ✅ **0.8.204–209** |
| **F5–F9** | Progressionsgraph | Start/Ziel, Gap-Prep, Skill-Expectations, Persistenz | ✅ **0.8.210–217** |
| **F10** | Progressionsgraph | Stufen-Lernziel-Gate, kein blindes Rank-Fallback | ✅ **0.8.218** |
| **F11–F12** | Progressionsgraph | Auto-Rematch, Spec-Refine, QS-Pipeline-Timing | ✅ **0.8.225–0.8.232** |
| **F13–F14** | Progressionsgraph | Katalog-Kontext + GraphEditor-Workbench | ✅ **0.8.233** |
| D | Übungs-Neuanlage | `planning_context` an `suggestExerciseAi` | ✅ **0.8.208** |
| **UX** | Progressionsgraph | Wizard/Stepper; PathBuilder-Parität Katalog | 🔲 |
| **D′** | Progressionsgraph | Auto KI-Gap-Fill bei persistent leeren Slots | 🔲 Backlog |
| **G** | Trainingsplanung | Kontext-Pack Gruppe/Historie, G0–G4 | 🔲 |
| **H** | Plattform | Technik-Katalog konfigurierbar; Mitai-Workflow | 🔲 Backlog |

---

## Phase F — Progressions-Roadmap (abgeschlossen bis F14)

Details und Module: **`PLANNING_PROGRESSION_GRAPH_KI.md`**.

### F0–F9 — (Kurz, siehe Ist-Doku)

- [x] F0 Foundation (0.8.204) — Spec, Pipeline-Skeleton, Prompts 078
- [x] F1 Deterministische Roadmap — Phase A/B/C heuristisch
- [x] F2 LLM Roadmap (0.8.205) — Prompts 078/079
- [x] F3 roadmap-first (0.8.206) — Match pro `stage_spec`, `roadmap_unfilled`
- [x] F4 UI Review (0.8.207) — `roadmap_override`, Major Steps editierbar
- [x] F5 Start/Ziel (0.8.210–214) — Prompt **087**, Zwei-Schritt-UI
- [x] F6 Gap-KI-Kontext (0.8.212–214) — `ExerciseGapFillPrepModal`
- [x] F7 Fähigkeiten-Scoring (0.8.215–216) — `planning_skill_expectations`
- [x] F8 Stufen-Details UI (0.8.216) — editierbare `stage_specs`
- [x] F9 Persistenz (0.8.217) — Migration **088** `planning_roadmap` JSONB

### F10 — Stufen-Qualität (0.8.218)

- [x] Stufen-Lernziel-Gate — kein Rank-Fallback ohne Pass
- [x] Anti-Pattern-Sanitizer, `stage_mismatch` → leerer Slot + Gap

### F11 — Auto-Optimierung (0.8.225–0.8.230)

- [x] `planning_path_rematch.py` — Rematch-Schleife für `rematch_slot` / `roadmap_unfilled`
- [x] `planning_path_refine_stage.py` — Spec-Schärfung aus QS
- [x] `planning_path_qa_pipeline.py` — mehrstufige QS

### F12 — Pipeline-Timing & Sync (0.8.231–0.8.232)

- [x] Post-Match-Gate vor Rematch-Akzeptanz
- [x] LLM Pfad-QS **nach** Rematch
- [x] Gap-Offers vor `path_qa`-Summary
- [x] Frontend: `applyMatchStepsToSlots` sync per `majorStepIndex`

### F13 — Katalog-Kontext (0.8.233)

- [x] `planning_catalog_context.py` — Fokus, Stil, Trainingsstil, Zielgruppe
- [x] Merge in `PlanningTargetProfile` + Text-Signale
- [x] Persistenz im Graph-Artefakt
- [x] Technik-Gates nur bei `topic_type == "technique"`

### F14 — GraphEditor Workbench (0.8.233)

- [x] `ProgressionGraphEditor` — primäre UI für Roadmap + Match + Lücken
- [x] Vier Planungskontext-Dropdowns im Editor
- [x] `progressionGraphDraft.js` — Artefakt + API-Payload

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

| Phase | Pfad-QS | Ergebnis |
|-------|---------|----------|
| Vor Roadmap/KI | ~65 % | Lücken, falsche Reihenfolge, Off-Topic |
| Nach Trainer-Roadmap + KI-Gap-Fill | **~88 % OK** | Vollständige Abdeckung; positive LLM-Hinweise |

**Fazit:** Workbench + Katalog + Roadmap sind universell; Technik-Hardcoding allein reicht für Didaktik nicht.

---

## UX — UI-Überarbeitung (offen)

- [ ] Wizard mit 4 Schritten (Ziel & Katalog → Roadmap → Match → Lücken)
- [ ] Progressive disclosure — Details in Panels
- [ ] PathBuilder-Parität: gleiche Katalog-Dropdowns wie GraphEditor
- [ ] QS-UI: positive LLM-Hinweise als Highlights
- Briefing: `PLANNING_PROGRESSION_GRAPH_KI.md` §12

---

## Phase D′ — Auto Gap-Fill (Backlog)

- [ ] Bei persistent `roadmap_unfilled` automatisch KI-Vorschlag vorbereiten (ohne manuelles Modal)
- [ ] Governance: Trainer bestätigt vor Persistenz

---

## Phase G — Trainingsplanung (komplexere Domäne)

**Ziel:** Einheiten, Rahmen-Slots, Abschnitte und parallele Streams KI-gestützt planen — **ohne** zweite Retrieval-Welt.

### Wiederverwendung aus Progressionsgraph

| Baustein | Progressionsgraph | Trainingsplanung |
|----------|-------------------|------------------|
| `PlanningTargetProfile` | Curriculum-Query + Katalog | Einheit + Abschnitt + Slot + Katalog + Historie |
| `planning_catalog_context` | Am Graph gespeichert | Pro Einheit / Slot / Voreinstellung |
| `planning_skill_expectations` | `progression_stage`, `progression_path` | **`training_section`**, **`framework_slot`** |
| `planning_exercise_retrieval` | Roadmap-Stufen-Match | `suggest_planning_exercises` — **bereits produktiv** |
| `planning_path_qa_pipeline` | Curriculum-QS | Abschnitts-QS (Kohärenz, Streams) |
| `planning_exercise_form_context` | Pfad-Lücken | Abschnitts-/Slot-Lücken |
| Roadmap-Pipeline | Major Steps über Wochen | **Nicht 1:1** — Phasen/Streams + Vorlagen |

### Was Phase G neu braucht

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

### Integrations-Reihenfolge G0–G4

| Schritt | Inhalt | Abhängigkeit |
|---------|--------|--------------|
| **G0** | Katalog in Einheits-Editor → bestehende Suggest-Pipeline | F13 ✅ |
| **G1** | Scope `training_section` + Skill-Erwartungen aktiv | F7 ✅ |
| **G2** | Abschnitts-QS (Hint-Struktur wie Graph) | F11–F12 ✅ |
| **G3** | Framework-Slot + Gap-Fill | G0, G1 |
| **G4** | Gruppenkontext-Pack | G0–G3 |

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

Details: **`PLANNING_PROGRESSION_GRAPH_KI.md`** §16 · Domäne **`DOMAIN_MODEL.md`** §1–2.

---

## Phase H1 — Katalog-Prompt-Snippets (Spez geplant)

**Spec:** **`PLANNING_CATALOG_PROMPT_SNIPPETS.md`**

Modulare Textbausteine pro Katalog-Ausprägung in LLM-Prompts (Roadmap, Pfad-QS, Stufen-Spec) — **nicht** neue Retrieval-Welt.

**Priorität (absteigend):** Primärfokus → Trainingsstil → Zielgruppe → Stilrichtung.

- [ ] `planning_catalog_prompt_snippets.py` + Registry (5–8 Snippets)
- [ ] Platzhalter `{{catalog_guidance_block}}` in Pfad-QS + Roadmap-Prompts
- [ ] Dev-Regression: Gewaltschutz / Breitensport / Kinder — QS-Hinweise passend zum Kontext

---

## Phase H — Plattform (Backlog)

- [ ] Technik-Disambiguierung konfigurierbar (DB statt `_GERI_TECHNIQUES` in Code)
- [ ] Mitai Workflow-Engine — erst wenn G0–G4 stabil

---

## Abhängigkeiten

| Von | Nach | Hinweis |
|-----|------|---------|
| F13 | G0, **H1** | Katalog-Kontext in Einheitsplanung; Snippets in LLM-Prompts |
| F7, F11 | G1, G2 | Skill-Expectations + QS-Muster |
| F4, F9 | G3 | Graph-Roadmap kann Rahmen referenzieren |
| G | H | Workflow-Engine lohnt bei verzweigten Planungsflows |

---

## Pflege

Bei Abschluss einer Teilphase: **`PLANNING_PROGRESSION_GRAPH_KI.md`** (Ist-Stand), diese Datei, `HANDOVER.md` §2.8, `PLANNING_EXERCISE_SUGGEST_CONTEXT.md` §24, Changelog in `version.py`.