shinkan-jinkendo/docs/architecture/PLANNING_CATALOG_PROMPT_SNIPPETS.md

# Planungs-KI — Katalog-Snippets für modulare Prompts

**Stand:** 2026-05-22  
**Status:** Spezifikation (Phase **H1** — Umsetzung offen)  
**Bezüge:** `PLANNING_PROGRESSION_GRAPH_KI.md` §4.4 · `AI_PROMPT_TARGET_ARCHITECTURE.md` §2.4 · `planning_catalog_context.py`

---

## 1. Problem

Seit **F13 (0.8.233)** fließen Primärfokus, Trainingsstil, Zielgruppe und Stilrichtung als `planning_catalog_context` in **Retrieval und Scoring** (`PlanningTargetProfile`).

Die **LLM-Prompts** (Roadmap, Stufen-Spec, Pfad-QS, Gap-Fill) erhalten diese Dimensionen **nicht** als differenzierte Bewertungs- und Planungslogik — höchstens indirekt über Freitext oder JSON-Kataloglisten in Intent-Prompts.

**Folge:** Ein Breitensport-Pfad kann mit Leistungsgruppen-Kriterien bewertet werden; Gewaltschutz wird wie Technik-Curriculum behandelt; QS-Hinweise und Rematch-Vorschläge passen fachlich nicht zum gewählten Kontext.

**Ziel:** Gleiche **Prompt-Basis**, aber **kaskadierte Snippet-Blöcke** pro Katalog-Ausprägung — keine Matrix aus Voll-Prompt-Kopien.

---

## 2. Priorität der Dimensionen (absteigend)

Verbindliche Reihenfolge bei Konflikten und beim Rollout:

| Rang | Dimension | DB-Tabelle | Snippet-Rolle |
|------|-----------|------------|----------------|
| **1** | **Primärfokus** | `focus_areas` | Definiert *worüber* geplant und bewertet wird (Technik-Curriculum vs. Gewaltschutz vs. Fitness …). **Dominant.** |
| **2** | **Trainingsstil** | `training_types` | Definiert *wie* trainiert wird (Methodik, Belastungsaufbau, Wettkampf vs. Breitenansatz im Training). |
| **3** | **Zielgruppe** | `target_groups` | Definiert *für wen* (Kinder, Breitensport, Leistungsgruppe) — Tempo, Komplexität, Sicherheit. |
| **4** | **Stilrichtung** | `style_directions` | Vereins-/Stil-Linie (Shotokan, WKF …) — **Nuancen**, kein neuer Planungstyp. |

**Kaskaden-Regel:** Bei widersprüchlichen Snippet-Aussagen gilt: Primärfokus → Trainingsstil → Zielgruppe → Stilrichtung.

---

## 3. Architektur — drei Schichten (Erinnerung)

| Schicht | Heute | Mit H1 |
|---------|-------|--------|
| **Retrieval** | Katalog-Gewichte in `merge_catalog_context_into_target` | unverändert |
| **Technik-Gates** | `planning_exercise_semantics.py`, nur `topic_type=technique` | unverändert |
| **LLM-Prompts** | kaum Katalog-spezifisch | **`catalog_guidance_block`** pro Aufruf |

Snippets **ersetzen** keine Technik-Disambiguierung und **duplizieren** keine Retrieval-Gewichte — sie steuern **Didaktik, Bewertungsmaßstäbe und Formulierung** für das Modell.

---

## 4. Snippet-Modell

### 4.1 Lookup-Schlüssel

Pro Katalog-Eintrag ein stabiler **`snippet_key`** (nicht nur numerische ID — IDs können sich in Dev/Import unterscheiden):

```
focus:{slug}          z. B. focus:gewaltschutz
training_type:{slug}  z. B. training_type:kumite
target_group:{slug}   z. B. target_group:breitensport
style:{slug}          z. B. style:shotokan
```

**Primär** aus `slug` der DB-Zeile; Fallback normalisierter `name` (ASCII, lower, `_`).

Mehrfachauswahl im UI: pro Dimension **höchstens ein Snippet** — die Zeile mit `is_primary: true`, sonst erste Zeile, sonst höchste `weight`.

### 4.2 Snippet-Inhalt (Struktur)

Jedes Snippet liefert strukturierte Textbausteine (Deutsch, für LLM):

| Feld | Pflicht | Inhalt |
|------|---------|--------|
| `planning_lens` | ja | 2–4 Sätze: Was ist das Planungsziel in dieser Dimension? |
| `qa_criteria` | ja | Bullet-artige Kriterien für Pfad-QS (was ist „gut“, was ist kein Mangel) |
| `roadmap_hints` | empfohlen | Stufenlogik, typische Phasen, was vermeiden |
| `anti_patterns` | optional | Explizite Fehlbewertungen vermeiden (z. B. „keine Wettkampf-Tiefe verlangen“) |
| `rematch_guard` | optional | Wann **kein** Auto-Rematch sinnvoll (Breitensport: keine Perfektions-Slots erzwingen) |

Phase **H1:** flache Markdown-Strings im Code-Modul.  
Phase **H2 (optional):** Tabelle `planning_catalog_prompt_snippets` oder JSONB an Katalog-Zeilen, Admin-editierbar.

### 4.3 Platzhalter in `ai_prompts`

Neue **gemeinsame** Platzhalter (Mustache), in alle betroffenen Prompts einfügen:

| Platzhalter | Bedeutung |
|-------------|-----------|
| `{{catalog_guidance_block}}` | Gerenderter Gesamttext (alle aktiven Snippets, kaskadiert) |
| `{{catalog_context_json}}` | Kompakte JSON-Zusammenfassung der gewählten IDs/Namen (Audit) |
| `{{#has_catalog_guidance}}` … `{{/has_catalog_guidance}}` | Block nur wenn mindestens ein Snippet aktiv |

**Optional fein (später):** `{{catalog_focus_snippet}}`, `{{catalog_training_type_snippet}}`, … — Phase H1 nur `_block` + JSON.

### 4.4 Betroffene Prompt-Slugs (Reihenfolge Einbindung)

| Priorität | Slug | Migration | Wirkung |
|-----------|------|-----------|---------|
| 1 | `planning_exercise_path_qa` | bestehend | Pfad-QS, `quality_score`, Empfehlungen |
| 2 | `planning_progression_roadmap` | 078 | Major Steps, Didaktik |
| 3 | `planning_progression_stage_spec` | 079 | Stufen-Gates, Erfolgskriterien |
| 4 | `planning_progression_start_target` | 087 | Start/Ziel-Extraktion |
| 5 | `planning_progression_goal_analysis` | 078 | Zielanalyse |
| 6 | Gap-Fill / Übungs-KI | 085+ | `planning_context` ergänzen |

Intent-Prompts (`planning_exercise_search_intent`, …) **optional** Phase H1.5 — dort bereits Katalog-JSON.

---

## 5. Builder (Backend)

**Neues Modul:** `backend/planning_catalog_prompt_snippets.py`

```python
def build_catalog_guidance_for_prompt(
    cur,
    catalog: Optional[ProgressionPlanningCatalogContext],
) -> Dict[str, str]:
    """
    Returns:
      catalog_guidance_block: str
      catalog_context_json: str
      has_catalog_guidance: bool
      snippet_keys: list[str]   # Metadaten für Logs/Tests
    """
```

**Ablauf:**

1. `catalog` aus Request oder `planning_roadmap.planning_catalog_context` (wie F13).
2. Pro Dimension aktives Item auflösen → `snippet_key` → Text aus Registry.
3. Snippets in **Prioritätsreihenfolge** §2 zu `_block` zusammenfügen (Überschriften: „Primärfokus“, „Trainingsstil“, …).
4. Fehlende Snippets: Dimension **weglassen** (kein Default-Text) — besser kein Snippet als falscher.

**Einbindung:** Orchestratoren rufen Builder auf und mergen in `variables` vor `load_and_render_ai_prompt`:

- `planning_exercise_path_qa.py` → `try_llm_qa_progression_path`
- `planning_progression_roadmap.py` (Roadmap-/Stage-Pipeline)
- `planning_exercise_path_builder.py` (catalog an QA/Match durchreichen)

`ProgressionPathSuggestRequest` trägt `planning_catalog_context` bereits — kein neues API-Feld nötig.

---

## 6. Beispiel-Snippets (Review-Entwurf)

### 6.1 Primärfokus — Gewaltschutz (`focus:gewaltschutz`)

**planning_lens:** Planung zielt auf Prävention, Deeskalation, Grenzen und sichere Übungsformen — nicht auf Wettkampf-Perfektion oder Technik-Show.

**qa_criteria:** Gute Pfade bauen Sicherheit, Kommunikation und Alternativen auf; „Lücken“ sind fehlende Deeskalations- oder Rollenspiel-Stufen, nicht fehlende Kick-Varianten.

**anti_patterns:** Nicht nach Kumite-Tiefe, Explosivität oder Wettkampf-Belastung bewerten.

### 6.2 Primärfokus — Technik / Kumite-Beinarbeit (`focus:kumite` o. ä.)

**planning_lens:** Curriculum für eine Technik oder Kumite-Teilaspekt; aufeinander aufbauende Belastung und Anwendungsnähe sind erwünscht.

**qa_criteria:** Kohärente Progression Grundlagen → Anwendung → Vertiefung; Übergänge ohne Sprünge; themenfremde Kraft-/Ausdauer-Inseln abwerten.

### 6.3 Trainingsstil — Breitensport (`training_type:breitensport` o. Name-Match)

**planning_lens:** Partizipation, Verständlichkeit, Freude am Bewegen; weniger maximale Spezialisierung.

**qa_criteria:** Hohe OK-Rate bei moderatem Schwierigkeitsanstieg; „Perfektion“-Stufen nur optional, nicht als Pflicht-Lücke.

**rematch_guard:** Keine leeren Slots erzwingen, nur um eine Leistungs-Perfektionsstufe zu füllen.

### 6.4 Zielgruppe — Leistungsgruppe (`target_group:leistungsgruppe`)

**qa_criteria:** Höhere Anspruchskurven, Belastungs- und Kombinationsprogressionen sind relevant; Lücken in Spezialisierung können echte Hinweise sein.

*(Weitere Snippets iterativ ergänzen — nicht alle Katalog-Zeilen sofort.)*

---

## 7. Rollout-Phasen

### H1 — Minimal viable (Progressionsgraph)

- [ ] Modul `planning_catalog_prompt_snippets.py` + Registry (5–8 Snippets: 2–3 Foki, 2 Trainingsstile, 2 Zielgruppen)
- [ ] Einbindung in **`planning_exercise_path_qa`** + **`planning_progression_roadmap`** + **`planning_progression_stage_spec`**
- [ ] Migration Prompt-Templates: Abschnitt `{{#has_catalog_guidance}}…{{/has_catalog_guidance}}`
- [ ] Tests: gleicher Pfad + unterschiedlicher Katalog → unterschiedlicher `catalog_guidance_block`; Snapshot QA-Variablen
- [ ] Dev-Regression: Gewaltschutz, Breitensport, Kinder — **Hinweistexte** müssen zum Kontext passen (nicht Mae-Geri-Kriterien)

### H1.5

- [ ] Rematch/Refine: `rematch_guard` aus Snippets respektieren (weniger Ping-Pong bei Breitensport)
- [ ] Intent-Prompts + Gap-Fill-Kontext

### H2 — Betrieb

- [ ] Snippets in DB, Admin-UI oder Markdown-Import
- [ ] Versionierung / Audit wie `ai_prompts`

### H3 — Phase G (Trainingsplanung)

- [ ] Gleicher Builder, anderer Orchestrator (Abschnitts-QS, Slot-Suggest)

---

## 8. Tests & Akzeptanz

| Test | Erwartung |
|------|-----------|
| `test_catalog_prompt_snippets_priority` | Bei Konflikt gewinnt Fokus-Snippet-Text in `_block`-Reihenfolge |
| `test_path_qa_variables_include_guidance` | Mit Gewaltschutz-Kontext enthält gerendeter Prompt „Deeskalation“ o. ä., nicht „Kumite-Perfektion“ |
| `test_path_qa_no_snippet_without_catalog` | Ohne Katalog: `has_catalog_guidance=false`, Prompt unverändert wie heute |
| Manuell | Mae-Geri-Pfad + Breitensport-Kontext: QS-Highlights ohne Leistungs-Belastungs-Forderungen |

**Nicht Ziel von H1:** Retrieval-Gewichte neu kalibrieren; Technik-Tuples externalisieren (separates Backlog **H** in Roadmap).

---

## 9. Abgrenzung zu anderen Fixes

| Thema | Dokument / Fix |
|-------|----------------|
| 88 % vs. 65 % falsche Pipeline | Evaluate-only für Pfad-QS; fairer Compare — Code-Stand 2026-05-22 |
| Triviale ID-Tausche im Dialog | `_filter_trivial_slot_diffs` |
| Katalog nur im Retrieval | F13 — bleibt, Snippets ergänzen LLM-Schicht |

Snippets lösen **fachliche Fehlbewertung** — nicht Pipeline-Inkonsistenz allein.

---

## 10. Changelog

| Datum | Änderung |
|-------|----------|
| 2026-05-22 | Erstfassung — Priorität Primärfokus → Trainingsstil → Zielgruppe → Stilrichtung; H1–H3 Rollout |