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)

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

F10 — Stufen-Qualität (0.8.218)

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

F11 — Auto-Optimierung (0.8.225–0.8.230)

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

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

• Post-Match-Gate vor Rematch-Akzeptanz
• LLM Pfad-QS nach Rematch
• Gap-Offers vor path_qa-Summary
• Frontend: applyMatchStepsToSlots sync per majorStepIndex

F13 — Katalog-Kontext (0.8.233)

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

F14 — GraphEditor Workbench (0.8.233)

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

F15 — Match-Dialog & getrennte Pfad-QS (2026-05-22, lokal)

• unified_slot_review — Dialog pro Slot (Bibliothek + KI, Stufen-Fit-Vergleich)
• Vorauswahl: Bibliothek nur bei Stufen-Fit ≥ 50 %; sonst KI bei leerem/schwachem Slot
• Übernahme ohne teure Auto-Nach-Bewertung; manuell „Graph bewerten“
• path_qa.roadmap_qa + path_qa.assignment_qa; Gesamt = Minimum
• findings_stale im Graph-Artefakt — Hinweis „Bewertung veraltet“ (persistiert)
• Slot-Key-Fix — Lernziel editierbar ohne Fokusverlust

Validierung (Referenz Mae Geri, 2026-05)

Phase	Roadmap-QS	Besetzung	Gesamt	Ergebnis
Vor Roadmap/KI	—	—	~65 %	Lücken, Off-Topic
Roadmap ok, Slots leer	~88 %	~8–15 %	~8–15 %	Besetzung fehlt
Nach Match + Fill	~88 %	hoch	~85 %+	Vollständige Abdeckung

Fazit: Roadmap-QS und Besetzungs-QS getrennt betrachten; Workbench + Katalog + Roadmap universell.

---

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.