shinkan-jinkendo/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md

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)

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:

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

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