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

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