CG-Feedback-Monitor/docs/FEEDBACK_CASCADE_PLAN.md

# Plan: Feedback-Neukonzeption, KI-Kaskadierung & UX

Stand: 2026-08-16 (Abgleich) · nur DEV (`AssigmentMonitorV2`)  
Voraussetzung: Bewertungsskala 1–10 umgesetzt (`docs/SCALE_1_TO_10.md`).

Dieses Dokument ist die **Arbeitsliste**. Status der offenen Punkte gesamt: `docs/STATUS_UND_OFFENE_PUNKTE.md`.

**Fortschritt 2026-08-16:** Pakete **0, 1, 1b, 2, 3, 6, 7**, **8.3** und **UX.1–UX.2** (Tokens + Shell) erledigt; **4/5** Code weitgehend; UX.3–UX.8 offen. **Nächster Fokus:** UX.3 Dashboard / UX.4 Meeting.

---

## Zielbild (festgezogen)

### Assignment-Feedback (Gesamtauswertung pro Person)

| Ebene | Inhalt |
|---|---|
| **Kategorie** | Score 1–10 · Benefits · Concerns (Gesprächsbasis) |
| **Dimension** | Benefits · Concerns — **3 bis max. 5** Hauptpunkte (verdichtet) |

- PDF enthält **beides** (Kategorie + Dimension) — intern/Manager-Gespräch, spätere Anbindung Erfassungssystem.
- Keine Pflicht-Rubrik „Reifegrad pro Scorelevel 1–10“; Score-Vorschlag primär aus **zeitgewichteten Meeting-Kategorie-Scores**, KI darf ±1 mit Begründung feinjustieren.
- Achievements/Development Needs → fachlich **Benefits/Concerns** (UI-Sprache umstellen).

### KI-Kaskade Feedback

```text
Stufe A  — 1 Call pro Kategorie (schmaler Kontext)
           → suggested Score, Benefits, Concerns (Kategorie)

Stufe B  — 1 Call pro Dimension
           Input: NUR Ergebnisse aus A (kein Rohprotokoll)
           → 3–5 Benefits + 3–5 Concerns (Dimension)
```

### KI-Kaskade Tagging („Vorschläge analysieren“)

```text
Nur ungetaggte Zeilen (bereits zugeordnete nie an KI)
→ Batches nach Zeilenanzahl UND Zeichenbudget
→ optional Hybrid: bei Monster-Batches Kriterien auf lokale Top-Kandidaten beschränken
→ Dimensions-Schnitt kein Standardweg
→ lokale Jaccard-Vorschläge + learnedPatternHints bleiben
```

---

## Entscheidungen (Nachtrag 2026-08-06)

1. **Score:** KI darf vorschlagen. Primärquelle = Meeting-Trend (wie bisherige Gewichtung). Keine 10-stufige Erwartungs-Rubrik als Voraussetzung; optional später globale Anker (z.B. 2/5/8/10), nicht jetzt.
2. **PDF:** Kategorie-Benefits/Concerns mit ausgeben.
3. **Tagging-Batches:** A (zeilen- + zeichenbasiert). B (Dimension) verworfen als Standard; Hybrid nur bei extrem großen Einträgen (Top-K Kriterien). C: getaggte Zeilen weiter ausschließen.

---

## Paket 0 — Aufräumen Skala 1–10 (Rest aus SCALE Phase 2–4)

Bereits weitgehend erledigt; nur nachziehen, was noch hinkt.

| # | Aufgabe | Done |
|---|---|---|
| 0.1 | Farbbänder speichern/laden (`getOrSeed`/`saveRatingColorBands` Server) — Hell-/Dunkelgrün unterscheidbar | ☑ `npm run smoke` + manuell |
| 0.2 | Chips Detail/History/PDF/MD aus `meetingCategoryRatings` (+ Fallback) | ☑ geprüft |
| 0.3 | Dimension-Prompts per „Auf Standard (1–10) setzen“ nachziehen / manuell testen | ☑ |
| 0.4 | Kurz-Smoke: Speichern Skala → Meeting-Einschätzung → Farben greifen nach Reload | ☑ |

**Exit:** Skala und Farben verhalten sich in Config, Meeting und Feedback konsistent.

---

## Paket 1 — Datenmodell Feedback (Benefits/Concerns)

| # | Aufgabe | Dateien (Orientierung) | Done |
|---|---|---|---|
| 1.1 | `FeedbackCategoryText`: `benefits`, `concerns`, `suggestedBenefits`, `suggestedConcerns` (+ Migration ALTER). Altes `text`/`suggestedText` entfernt (Dev: ggf. `npm run db:reset` oder Spalten bleiben ungenutzt in alter SQLite) | `types.ts`, `tableRegistry`, UI/PDF | ☑ |
| 1.2 | Dimension: DB `achievements`/`developmentNeeds` behalten; UI/PDF-Labels **Benefits/Concerns** | | ☑ |
| 1.3 | CRUD unverändert (generisch); Parser + Feedback-Seite + PDF angepasst | | ☑ |
| 1.4 | `npx tsc -b` grün | | ☑ |

**Exit:** Persistenz für Kategorie- und Dimension-Benefits/Concerns inkl. `suggested*`.

---

## Paket 2 — Prompt-Engine Stufe A (pro Kategorie)

| # | Aufgabe | Done |
|---|---|---|
| 2.1 | Neues Template (AppSettings oder pro Dimension): Kategorie-Call — Platzhalter nur für **eine** Kategorie (Struktur, Kriterien-Scores/Notizen dieser Cat, Meeting-Cat-Scores/Trend, getaggte Zeilen dieser Cat) | ☑ |
| 2.2 | Antwortformat Marker z.B. `SCORE:`, `BENEFITS:`, `CONCERNS:` — Parser analog `parseDimensionAiResponse` | ☑ |
| 2.3 | Score-Vorschlag: berechneten Trend **im Prompt vorgeben**; KI nur bestätigen oder ±1 mit Begründung (nicht frei aus Protokoll erfinden) | ☑ |
| 2.4 | Sequenz: alle Kategorien eines Institutee (Fortschritt, Teilfehler, Retry pro Kategorie) | ☑ |
| 2.5 | Config-UI: Kategorie-Prompt editierbar (+ Reset), Platzhalter-Legende | ☑ |

**Exit:** „KI generieren“ füllt `suggested*` auf Kategorie-Ebene; Score-Badge aus Trend bleibt führend.

---

## Paket 3 — Prompt-Engine Stufe B (Dimension verdichten)

| # | Aufgabe | Done |
|---|---|---|
| 3.1 | Dimension-Template umbauen: Input = Kategorie-Benefits/Concerns + Scores der Dimension; **kein** Rohprotokoll | ☑ |
| 3.2 | Output: genau 3–5 Benefits, 3–5 Concerns; Parser/Validierung (zu viele kürzen-Hinweis oder Prompt-Zwang) | ☑ |
| 3.3 | Orchestrierung: erst alle Cats der Dim (A), dann ein Call B; fehlende Cats = Retry A vor B | ☑ |
| 3.4 | Bestehende Dimension-Prompts in DB: Reset-Button / Sync auf neues Default-Template | ☑ |

**Exit:** Dimension-Texte sind Verdichtung, nicht Parallel-Erfindung aus dem Protokoll.

---

## Paket 4 — Feedback-UI

| # | Aufgabe | Done |
|---|---|---|
| 4.1 | Pro Kategorie: ScorePicker + Trend/KI-Score-Vorschlag („Übernehmen“) + Benefits/Concerns (editierbar + suggested-Boxen) | ☑ Code · Smoke ☐ |
| 4.2 | Pro Dimension: nur Benefits/Concerns (3–5), suggested übernehmen/verwerfen | ☑ Code · Smoke ☐ |
| 4.3 | Alten Ein-Text-pro-Kategorie und Achievements/DevNeeds-Labels entfernen bzw. umbenennen | ☑ Code · Smoke ☐ |
| 4.4 | „Trend in Text“ → sinnvoll auf Concerns oder Benefits mappen (Regel festlegen, z.B. Verschlechterung→Concern) | ☑ |
| 4.5 | Fortschrittsanzeige Generierung: Kategorie X/Y, dann Dimension Z | ☑ |

**Exit:** Direktgespräch möglich: Kategorie-Details + Dimensions-Hauptpunkte auf einer Seite.

---

## Paket 5 — PDF & sonstige Exporte

| # | Aufgabe | Done |
|---|---|---|
| 5.1 | `InstituteeFeedbackDocument` / Assignment-Report: pro Kategorie Score + Benefits + Concerns; pro Dimension Benefits + Concerns | ☑ Code · Smoke ☐ |
| 5.2 | Nur finale Felder, nie `suggested*` | ☑ Code · Smoke ☐ |
| 5.3 | Markdown/JSON Assignment-Feedback falls vorhanden nachziehen | ☐ |

**Exit:** Internes PDF für Manager-Gespräch brauchbar.

---

## Paket 6 — Tagging-Kaskade (Zeichen-Batches)

| # | Aufgabe | Done |
|---|---|---|
| 6.1 | Hilfsfunktion: offene Zeilen sammeln (unverändert: ohne bereits Getaggte, ohne Kundenzitate wie bisher) | ☑ `collectOpenProtocolLines` |
| 6.2 | Batch-Builder: max. Zeilen **und** max. Zeichensumme (Konstanten in `constants` oder AI_CONFIG, konfigurierbar später) | ☑ `buildCharAwareBatches` / `AI_CONFIG.taggingBatch*` |
| 6.3 | `analyzeSuggestions`: Schleife über Batches; Ergebnisse mergen; Fortschritt „Batch i/n“; Teilfehler retrybar | ☑ |
| 6.4 | Hybrid-Notnagel: wenn ein Batch trotz 1 Zeile zu groß (Struktur+Text), `{{KRITERIEN_STRUKTUR}}` auf Jaccard-Top-K der Batch-Zeilen beschränken | ☑ `narrowCriteriaIdsForBatch` |
| 6.5 | `MUSTER:`-Block: nach allen Batches einmal zusammenführen/schreiben oder nur aus Batches mit Treffern — Regel dokumentieren | ☑ Merge, später überschreibt früher; ein DB-Write am Ende |
| 6.6 | Info-Zeile + Rohantwort weiter nutzbar (pro Batch oder letzte) | ☑ Rohantworten mit Batch-Trennern |

**Exit:** Lange Protokolle brechen nicht mehr am Einzelcall; getaggte Zeilen bleiben draußen.

---

## Paket 7 — Robustheit KI-Client (gemeinsam)

Betrifft Feedback- und Tagging-Calls.

| # | Aufgabe | Done |
|---|---|---|
| 7.1 | Timeouts / Abbruch klar melden (nicht still) | ☑ `callOpenRouter` 90s + Abort-Meldung |
| 7.2 | Retry mit Backoff für transient failures (einmalig) | ☑ 429/5xx/Netz/Timeout |
| 7.3 | Grobe Prompt-Größen-Schätzung vor Call → Warnung oder Auto-Split | ☑ Soft-Warn + Hard-Limit; Tagging auto-split (6) |
| 7.4 | Gleiche `aiClient`-Hilfen für Feedback und Tagging | ☑ |

**Exit:** Abbrüche sind erklärbar und oft automatisch reparierbar.

---

## Paket UX — Professionelle Oberfläche (Capgemini-Tool, kein Marketing-Landing)

Bisher wirkt die App funktional, aber wie ein schneller Prototyp (graue Fläche, Emoji-Navigation, uneinheitliche Karten/Abstände). Ziel: **ruhig, markenklar, gut lesbar im Direktgespräch und im Live-Meeting** — nicht „bunte Dashboard-Show“.

### Leitplanken

- Capgemini-Brand `#0070AD` / Tailwind `brand` als Primärsignal; keine lila/Indie-Themes.
- Bestehende Interaktionsmuster behalten (Tabs, ScorePicker, Tag-Picker) — visuell vereinheitlichen, nicht neu erfinden.
- Schreibfluss im Meeting schützen (keine zusätzlichen Overlays beim Tippen).
- Emojis in Nav/Buttons schrittweise durch klare Labels oder einfache Icons ersetzen (oder stark reduzieren).
- Typografie und Abstände einmal zentral (`index.css` / kleine UI-Primitives), nicht Seite für Seite wildwuchs.

| # | Aufgabe | Done |
|---|---|---|
| UX.1 | **Design-Tokens:** Schrift, Abstände, Radius, Schatten, Flächen (`bg-app`, `surface`, `border-subtle`) in `index.css` / `@theme` — App-Shell (`App.tsx`) darauf umstellen | ☑ |
| UX.2 | **App-Chrome:** Header (Titel/Kontext), Bottom-Nav ohne Emoji-Overload, aktiver Zustand klar, sichere Touch-Targets | ☑ |
| UX.3 | **Dashboard / Assignment-Listen:** einheitliche Zeilen/Kacheln, Status, Typografie-Hierarchie (Nummer, Kunde, Institutees) | ☐ |
| UX.4 | **Meeting-Live-UX:** Einschätzung + Protokoll dichter und ruhiger; ScorePicker/Chips konsistent; Fokus auf Tippen + schnelle Scores | ☐ |
| UX.5 | **Feedback-Seite:** nach Paket 4 — klare Hierarchie Dimension → Kategorie; Benefits/Concerns optisch getrennt; KI-Vorschläge als „Entwurf“, nicht als Lärm | ☐ |
| UX.6 | **Config:** Tabs und Formulare angleichen (Skala, KI-Prompts, Struktur) — gleiche Button-/Hinweis-Muster | ☐ |
| UX.7 | **Leere Zustände & Fehler:** kurze, professionelle Leer-/Fehlertexte statt stiller Lücken | ☐ |
| UX.8 | **PDF-Feinschliff:** Typo/Abstände an Capgemini-Report-Anmutung (ohne Corporate-Template-Zwang) | ☐ |

**Timing:** UX.1–UX.2 früh (nach Paket 0) als Fundament. UX.4 mit Meeting-Arbeit; **UX.5 bewusst nach Paket 4** (sonst doppelte UI-Arbeit). UX.3/6/7 parallel zu funktionalen Paketen möglich. UX.8 nach Paket 5.

**Exit:** App wirkt wie ein internes Capgemini-Fachtool: einheitlich, ruhig, brandklar — ohne Feature-Regression.

---

## Paket 8 — SCALE / Struktur Prio-2 und bekannte Offenheiten

Nicht blockierend für Pakete 1–7 / UX; einplanen wenn Kapazität.

| # | Aufgabe | Quelle | Done |
|---|---|---|---|
| 8.1 | Sichtbarkeit Dim/Cat pro Typ — **vorgezogen nach Paket 1b** | SCALE Phase 6 | → 1b |
| 8.2 | Notation-Schnellbuttons / mobile Hit-Areas (kann in UX.4 aufgehen) | SCALE Phase 5 | ☐ |
| 8.3 | Dexie/IndexedDB-Legacy entfernen | STATUS T2 | ☑ |
| 8.4 | Server Seed-if-empty Assignment-Typen/Struktur | STATUS N5 (weitgehend durch `setup` ersetzt) | ☐ optional |
| 8.5 | Evaluation.tsx / FeedbackDraftPage auf neue Benefits/Concerns + Bänder prüfen oder Legacy deprecaten | STATUS T5 | ☐ |
| 8.6 | Datenschutz: Hinweis Tagging+Feedback (externe API) vor Prod | STATUS T6 | ☐ |

---

## Empfohlene Abarbeitungsreihenfolge

```text
0 / 1 / 1b / 2 / 3 / 6 / 7 / 8.3           ← erledigt
 → UX.1–UX.2 Tokens + Shell               ← erledigt
 → UX.3 Dashboard · UX.4 Meeting          ← nächster UX-Schritt
 → UX.5 Feedback · UX.6 Config · UX.7–8
 → T4 Smoke / 5.3 parallel möglich
 → T1 / T5 / T6 nach Bedarf
```

**Hinweis:** Feature-Stabilität vor UX war Absicht; UX.1–UX.2 sind Fundament für die Folgeschritte.

**Warum 1b vor 2 (historisch):** Stufe A und Feedback-UI müssen nur Kategorien/Dimensionen des Assignment-Typs sehen — erledigt.

---

## Paket 1b — Feedback-Struktur je Assignment-Typ (vorziehen aus 8.1)

Ziel: Ein Assignment-Typ blendet Dimensionen und/oder Kategorien aus → Meeting-Einschätzung, Tagging-Struktur und Assignment-Feedback arbeiten auf **derselben** Teilmenge.

| # | Aufgabe | Done |
|---|---|---|
| 1b.1 | Kanonischer Helper z.B. `resolveVisibleStructure(allDims, allCats, allItems, criteriaIds)` → `{ dimensions, categories, items }` (Cats ohne Items und Dims ohne Cats entfallen) — baut auf `filterVisibleFeedbackStructure` auf | ☑ |
| 1b.2 | Überall verdrahten: MeetingView, Assessment, Feedback-Seite, Tagging-Prompt, PDF-Feedback-Teil, History/Detail wo nötig | ☑ |
| 1b.3 | Config Ass.-Typen: Auswahl auf **Dimension- / Kategorie-Ebene** (Checkboxen), persistiert weiter als `criteriaIds` (alle Items der gewählten Cats) — kein zweites Parallel-Feld nötig | ☑ |
| 1b.4 | Leere `criteriaIds` = alles sichtbar (unverändert); Smoke mit Typ der z.B. nur 1–2 Dimensionen hat | ☐ manuell |

**Nicht nötig jetzt:** separates `dimensionIds[]`/`categoryIds[]` in der DB, solange die UI Dim/Cat pflegt und auf `criteriaIds` mappt.

**Exit:** Feedback und Einschätzung zeigen für denselben Assignment-Typ dieselbe Struktur; KI-Kaskade kann darauf aufsetzen.

---

## Empfohlene Abarbeitungsreihenfolge (Detail)

```text
0 → 1 → 1b → (6+7 optional) → 2 → 3 → 4 → 5 → 8 → UX
```

**Alternative, wenn Feedback-Calls zuerst stören:** nach 1b sofort `2→3→4→5`, Tagging `6→7` dazwischen wenn Abbrüche blockieren.

---

## Nicht-Ziele (jetzt)

- Produktiv-Migration / Mapping alter Enum-Skala
- 10-stufige Score-Rubrik pro Kategorie
- Dimensions-Score als eigene Pflicht-Ebene
- Tagging-Batches standardmäßig nach Dimension schneiden
- Automatischer KI-Call beim Meeting-Öffnen
- Anbindung externes Erfassungssystem (PDF/Struktur vorbereiten reicht)
- Komplett-Redesign als Marketing-Landing / Dark Mode / Illustration-Heavy UI

---

## Abnahmekriterien (Gesamt)

1. Feedback-Seite zeigt Kategorie-Score + Benefits/Concerns und Dimensions-Hauptpunkte (3–5).
2. Generierung läuft kaskadiert (Cat → Dim), Teilfehler retrybar, Prompt ohne wiederholtes Vollprotokoll in Stufe B.
3. PDF enthält Kategorie- und Dimension-Benefits/Concerns (final).
4. „Vorschläge analysieren“ arbeitet in zeichenbewussten Batches; bereits getaggte Zeilen gehen nicht an die KI.
5. Score-Vorschlag bleibt an Meeting-Trend gekoppelt; KI erfindet keinen Score aus dem Nichts.
6. Oberfläche wirkt professionell und einheitlich (Shell, Typo, Abstände, Meeting + Feedback).
7. `npx tsc -b` fehlerfrei; manuelle Smoke-Tests Meeting + Feedback + PDF.

---

## Nächster Schritt

Beim Start der Umsetzung: **Paket 0 kurz verifizieren**, optional **UX.1–UX.2** für den ersten visuellen Sprung, dann entscheiden ob zuerst **Paket 6 (Tagging)** oder **Paket 1+2 (Feedback-Schema/KI)**.