shinkan-jinkendo/.claude/docs/functional/AI_EXERCISE_ASSISTANT_VISION.md

KI-Unterstützung bei Übungen – Produkt-Vision

Version: 0.1
Datum: 2026-05-22
Status: Zielbild / Anforderungsgrundlage (nicht gleich Ist-Spec – technische Schnittstellen: technical/KI_FEATURES_SPEC.md, technical/AI_PROMPT_SYSTEM_SPEC.md, technical/AI_TRAINING_PLANNING_CONCEPT.md §1.1)
Zielgruppe: Product, Trainer-UX, später Admin-Werkzeuge

---

1. Übergeordnete Prinzipien

1. Immer Vorschlag, nie blind überschreiben
   Die KI liefert Vorschläge (Änderungen, Ergänzungen, Strukturen). Bestehende Inhalte werden nicht still ersetzt. Übernahme erfolgt durch den Nutzer: teilweise (Felder/Stellen/Blöcke) oder komplett („Vorschlag gesamt akzeptieren“).

2. Granulare Anforderung im Editor
   Innerhalb einer Übung soll KI-Unterstützung feldbasiert oder bereichsbasiert auslösbar sein (z. B. nur „Anleitung schärfen“, nur „Fähigkeiten“, nur „Variantenrahmen“) oder als Komplettüberarbeitung mit klarem Warnhinweis (Umfang/transparenter Diff).

3. Nachweisliche Herkunft
   Übernommene KI-Inhalte werden technisch dort abgebildet, wo bereits vorgesehen (z. B. summary_ai_generated, exercise_skills.ai_suggested) und um analogen Hinweis für weitergehende Textfelder/Varianten erweitert, sobald Implementierung konkret wird.

---

2. Funktionsbereiche (Vision)

2.1 Von der Idee zur kompletten Übung („Zielausbau“)

Einstieg minimal: Kurzbeschreibung oder Stichwort, Ziel („was soll erreicht werden?“), wenige Rahmenparameter (z. B. Fokusbereich, Trainingszeit, Teilnehmerzahl, Alter, Platzausstattung, Sicherheitshinweise – konkrete Dropdowns/Freifelder in UX später festlegen).

KI-Aufgabe: aus diesem dünnen Kontext einen übernehmbaren Entwurf einer ganzen Übung erzeugen: Titel‑Vorschlag, Ziel-/Durchführungstext, Sicherheit/Organisation, ggf. Trainerhinweise – immer als Vorschlagspaket, nicht als Speicher ohne Bestätigung.

Abgrenzung: Kombinationsübungen / komplexe Methodenprofile können phasenweise später einbezogen werden (Verweis Fachspez Trainingsmodule).

2.2 Anleitung (Durchführung / „Ausführung“) maximal hilfreich

Ziel: Die Ausführungs-/Anleitungsbereiche sollen sich didaktisch klar, teilbar und wieder verwendbar lesen – ohne den Trainer zu entmindigen.

KI-Aufgabe: Überarbeitungsvorschlag für Struktur (nummerierte Schritte, Zeiten pro Block, häufige Fehler, Progressionshinweise innerhalb der Übung wo sinnvoll). Selektiver Aufruf: nur diese Felder oder nur ein markierter Abschnitt (wenn UX Textauswahl unterstützt).

2.3 Kurzbeschreibung (summary)

KI-Aufgabe: Aus den relevanten Übungstexten eine Liste-/Karte-taugliche Kurzfassung generieren — wie in KI_FEATURES_SPEC.md beschrieben, mit Ablehnen / Bearbeiten / Übernehmen.

2.4 Einordnung – primär Fähigkeiten

KI-Aufgabe: automatische Erkennung und Zuordnung zum globale Skills-Katalog inklusive:

• Intensität (exercise_skills)
• Skill-Level: required_level / target_level nach kanonischen Slugs (Backend-konform)
• is_primary / Priorisierung wo fachlich sinnvoll

Prompt-Kontext für Qualität: Stammfelder wie skills.description, karate_relevance, relevance_level, focus_areas, optional skill_level_definitions nur für eine kurze Kandidatenliste (zweite Runde möglich) – keine vollständigen Romane für den gesamten Katalog auf einmal.

2.5 Varianten (optional, später prioritär erwägenswert)

Vision: Aus Ziel-/Durchführungstext mehrere sinnvolle Ausprägungen als Übungsvarianten vorschlagen oder einzelne erzeugen (progression, Schwierigkeit, andere Paararbeit, Gerätevariation) mit übernehmbarem Datenmodell gleich dem bestehenden exercise_variants.

Randbedingungen: Validierung gegen Übungstyp (Kombinationsübungen ohne Varianten laut Produktstand), keine Halluzination fremder IDs.

---

3. Kontextbezug später: Nachbearbeitung aus der Trainingsplanung

Vision: Hinweise aus der Nachbearbeitung einer Trainingseinheit (Ist‑Minuten, Trainer-Notizen, Abweichungen „was lief nicht?“ – je nach Datenmodell) fließen optional als Kontext in eine erneute KI-Überarbeitung der betroffenen Übung ein („Übung aus den Erfahrungen der Gruppe verbessern“).

Konsequenz technisch später: Zugriffsrechte, Mandant, keine unzulässige Verknüpfung personenbezogener Sportlerdaten; Aggregation auf Einheit-/Gruppe und bereits dokumentierte Trainer-Insights.

---

4. Admin: Massenverarbeitung und Analyse

Vision für Plattform-/Vereins-Admins:

Thema	Richtungsziel
Massenverarbeitung	Batch: z. B. Zusammenfassungen nachziehen, fehlende Skills vorschlagen, einheitlicher Stil bei importiertem Bestand — immer mit Review-Queue, nicht ohne menschliche Freigabe skalierungskritisch.
Analyse / Qualität	Werkzeugkasten oder Berichte: welche Übungen sollten überarbeitet werden? z. B. leere/kurze summary, fehlende goal/execution, fehlende oder widersprüchliche Skill-Zuordnung, Import-Herkunft ohne Plausibilität, Kombi-Slots unvollständig, sehr alte Imports.
Lückenkarten	Z. B. Abgleich gegen Skill-Discovery/Profil-Analysen („keine Übung deckt Fähigkeit X ab“ auf gewähltem Korpus); Verbindung zu skill-discovery entscheidend später im Detail (kein automatischer Rewrite ohne Policy).

Governance: Sichtbarkeit (official, Verein), Rechte (Superadmin vs. Vereinsinhalt), Audit der KI-Anwendung bei Massenjobs.

---

5. Phasierung (überarbeitungsfähig)

Phase	Inhalt
P0	KI-Service + Prompts aus DB + Suggestion-only UX; Kern: Summary + Skills (wie Spec-Minimum), ein Feld / Komplettpaket mit Diff nach UX.
P1	Anleitung überarbeiten + „von Idee zur Übung“ (Zielausbau) mit Rahmenparameter-Form
P2	Variantenvorschläge mit strenger Validation
P3	Planungs-/Nachbereitungskontext
P4	Admin Massen-/Analyse (Queue + Reports + Governance)

---

6. Offene Produkt-/Fachfragen

• Minimaler Parameterbau beim Zielausbau (Pflicht vs. optional).
• Umgang mit Medien/Inline-Verweisen beim KI-Text – nichts zerstören, Platzhalter erhalten (siehe Medien-Spec §11).
• Kombinationsübungen: welche Teilaspekte dürfen KI anfassen?
• Limits: Tokens, Rate-Limits, Kostenüberwachung pro Verein/global.