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

```python
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)

```json
{
  "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)

```json
{
  "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)

```json
{
  "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):**

```json
{
  "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) | 🔲 |
| **F4** | UI Roadmap-Review | 🔲 |
| **F5** | Trainingsplanung: eigene Pipeline + ggf. Workflow-Engine | 🔲 |

---

## 9. Changelog

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