shinkan-jinkendo/.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md

Planungs-KI — Progressions-Roadmap (Phase F)

Version: 0.1
Datum: 2026-06-07
Status: VERBINDLICHE ZIELARCHITEKTUR — Umsetzung gestartet (0.8.204+)
Geltungsbereich: Progressionsgraph (exercise_progression_graphs) — ohne Gruppenanalyse

Bezüge:
working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md · working/AI_PLANNING_KI_MULTISTAGE_FORECAST.md · technical/AI_TRAINING_PLANNING_CONCEPT.md · technical/AI_PROMPT_TARGET_ARCHITECTURE.md · docs/architecture/PLANNING_KI_ROADMAP.md · docs/HANDOVER.md

---

1. Entscheidung (2026-06-07)

1.1 Problem

Der Pfad-Builder (Phase C3/E) ist retrieval-first: Zieltext → N Übungen aus der Bibliothek → QS nachbessern. Das entspricht nicht der menschlichen Planung (Ziel → Roadmap → Stufenspezifikation → Übung).

1.2 Festlegung

Thema	Entscheidung
Progressionsgraph	Roadmap-first — Phasen A→B→C, dann Bibliothek (D), dann Feinausplanung (E)
Gruppenanalyse	Nicht in der Graphen-Pipeline — erst bei Trainingsplanung (Einheit/Rahmen)
Mitai Workflow-Engine	Nicht jetzt portieren — Workflow-lite (PlanningProgressionPipeline), später workflow-ready
Ein Mega-Prompt	Verboten — validierte Artefakte pro Phase

1.3 Abgrenzung Trainingsplanung

Progressionsgraph-Pipeline     Trainingsplanungs-Pipeline (später)
─────────────────────────     ───────────────────────────────────
Ziel + N Major Steps          Gruppe + Historie + Termin + Rahmen
Kein Gruppenkontext           Kontext-Pack S0 (AI_PLANNING_KI_MULTISTAGE_FORECAST)
Curriculum / Technikpfad      Session-Füllung / Reihenfolge / Zeiten

---

2. Menschliches Vorbild → Phasen

Mensch	Phase	Output-Artefakt	LLM
Startpunkt + Zielzustand	A Zielanalyse	goal_analysis	Optional (klein)
Zwischenziele, gewichten, auf N reduzieren	B Roadmap	roadmap (micro_objectives[], major_steps[N])	Ja
Belastung, Übungstyp, Lernziel je Stufe	C Stufenspezifikation	stage_specs[]	Teilweise
Bibliothek / Brücke	D Match	step_matches[] oder gaps[]	Nein (Retrieval)
Skizze + Feinplan	E Übungsentwurf	bestehend suggestExerciseAi	On-demand

Phase B = Kern: 8–12 micro_objectives → Konsolidierung → exakt max_steps major_steps.

---

3. Pipeline-Orchestrator (Workflow-lite)

Modul: backend/planning_progression_roadmap.py

ctx = ProgressionRoadmapContext(goal_query=..., max_steps=N, semantic_brief=...)
ctx = phase_a_goal_analysis(ctx)       # deterministisch + optional LLM
ctx = phase_b_roadmap(ctx)             # micro → major
ctx = phase_c_stage_specs(ctx)         # je major_step
# Phase D/E: bestehende path_builder / retrieval / ai_fill — speisen von ctx.major_steps

Jede Phase: (ctx) → ctx, Zwischenergebnisse in API-Response für Human-in-the-loop (Roadmap-Review vor Übungs-Match).

Später: jede Phase = Workflow-Knoten (Mitai-kompatibel), keine API-Änderung an Artefakten.

---

4. JSON-Artefakte (Pydantic)

4.1 goal_analysis (Phase A)

{
  "primary_topic": "Mae Geri",
  "start_assumption": "Grundkenntnisse der Standführung, keine Perfektion",
  "target_state": "Sicherer, präziser Mae Geri unter Belastung und in Anwendung",
  "success_criteria": ["saubere Kammerhaltung", "Hüftführung", "Kime am Zielpunkt"],
  "constraints": { "partner_required": false, "equipment": [] }
}

4.2 roadmap (Phase B)

{
  "micro_objectives": [
    { "id": "m1", "phase": "grundlage", "title": "Stellung und Kammerhaltung", "weight": 0.9, "depends_on": [] },
    { "id": "m2", "phase": "vertiefung", "title": "Hüft- und Kniekoordination", "weight": 0.85, "depends_on": ["m1"] }
  ],
  "major_steps": [
    {
      "index": 0,
      "phase": "grundlage",
      "learning_goal": "Stabile Mae-Geri-Grundstellung",
      "consolidates": ["m1"],
      "rationale": "Einstieg ohne Perfektionsdruck"
    }
  ],
  "consolidation_notes": ["Perfektion mit Anwendung zusammengeführt"]
}

4.3 stage_spec (Phase C, je Major Step)

{
  "major_step_index": 2,
  "learning_goal": "…",
  "load_profile": ["präzision", "koordination"],
  "exercise_type": "kihon_einzel",
  "success_criteria": ["…"],
  "anti_patterns": ["reine Kraftübung ohne Technikbezug"]
}

---

5. API (schrittweise)

5.1 Erweiterung POST /api/planning/progression-path-suggest

Feld (neu)	Default	Bedeutung
roadmap_first	false → später true	Roadmap-Pipeline vor Retrieval
include_roadmap_preview	true wenn roadmap_first	Artefakte A/B/C in Response

Response (neu):

{
  "progression_roadmap": {
    "goal_analysis": { },
    "roadmap": { },
    "stage_specs": [ ],
    "pipeline_phase": "roadmap_v1"
  },
  "steps": [ ]
}

Übergangsphase (0.8.204): include_roadmap_preview=true liefert Roadmap parallel zum bestehenden retrieval-first Pfad — UI kann Roadmap reviewen, Schritte bleiben vorerst retrieval-basiert.

Zielphase (F2): roadmap_first=true — Retrieval pro Major Step aus stage_specs, nicht mehr iterativ „beste nächste Übung“.

5.2 Prompt-Slugs — nur in ai_prompts, nie im Code

Regel: Prompt-Texte leben ausschließlich in der Tabelle ai_prompts (Superadmin bearbeitbar, Vorschau, openrouter_model pro Zeile). Python referenziert nur Slugs (PROMPT_SLUG_* in planning_progression_roadmap.py). Kein verstecktes Hardcoding von Templates.

Slug	Phase	Migration
planning_progression_goal_analysis	A	078
planning_progression_roadmap	B	078
planning_progression_stage_spec	C	079

API: include_llm_roadmap (Default true) — lädt Prompts via load_and_render_ai_prompt. Bei Fehler/kein OpenRouter: deterministischer Fallback (kein stilles Versagen).

Response: prompt_slugs (genutzte Slugs), prompt_slug_catalog (Referenz), llm_*_applied Flags.

Admin: Templates unter Kategorie training pflegen — siehe AI_PROMPT_SYSTEM_SPEC.md.

---

6. UI-Roadmap

1. F1: Roadmap-Box unter Ziel-Eingabe (Major Steps als Karten, editierbar) — vor Übungsliste
2. F2: Match-Ergebnis pro Major Step (Bibliothek / Lücke / KI anlegen)
3. F3: roadmap_first als Default im Graph-Builder

---

7. Was bewusst nicht in Phase F

• Gruppen-Historie, Belastungssteuerung der Gruppe
• Mitai workflow_engine Port
• Vollautomatisches Speichern ohne Trainer-Review

---

8. Implementierungsstände

ID	Inhalt	Status
F0	Spec + Doku + planning_progression_roadmap.py Scaffold	🔄 0.8.204
F1	include_roadmap_preview in API + deterministische A/B	🔄 0.8.204
F2	LLM Phase A/B/C über ai_prompts (078/079), include_llm_roadmap	🔄 0.8.205
F3	Retrieval aus stage_specs (roadmap_first)	✅ 0.8.206
F4	UI Roadmap-Review	✅ 0.8.207
F5	Trainingsplanung: eigene Pipeline + ggf. Workflow-Engine	🔲

---

9. Changelog

• 2026-06-07: Erstfassung — Roadmap-first Entscheidung, Abgrenzung Graphen vs. Planung, Workflow-lite.