# Intent: Metriken über wiederholte Läufe desselben Intents, verglichen mit direktem Single-Prompt an ein starkes Modell ## Umsetzungsstand Umgesetzt: `metrics.py` (opt-in `run_history` je Karte, gated über `BOARD_METRICS_SLUGS`), `metrics_baseline.py` (manuelles CLI-Pilot-Tool, `worker.run_baseline()`), `merged_board()`s `metrics_summary`-Feld und `board.html`s `appendMetricsBadge()`. Details, Feldnamen und exakte Aufrufweise stehen in `README.md`s Abschnitt "Run-metrics pilot" -- diese Karte beschreibt weiterhin nur Ziel und Scope-Grenzen, nicht die Implementierung im Detail, um Dopplung zu vermeiden. Alle 16 neuen Tests (`MetricsModuleTests`, `RunBaselineTests`, `CompletionWatcherMetricsTests`, `MergedBoardMetricsSummaryTests`, `MetricsBoardFrontendTests`) plus alle 132 vorher bestehenden laufen grün (148/148, `nix shell nixpkgs#python3 -c python3 -m unittest test_board_agent`). Noch offen, bewusst nicht Teil dieser Umsetzung: tatsächliche Token-/Kostenerfassung (kein Runtime liefert das aktuell zuverlässig genug, siehe "Offene Risiken" unten -- das Feld existiert im Schema, bleibt aber in der Praxis meist leer) und die eigentliche Pilot-Auswertung (welche 2-3 Intents, wie oft wiederholt) -- das ist eine Nutzungsentscheidung, kein Code. ## Ausgangslage `docs/research/intent-board-architektur-ux-evaluation.md` stellt fest, dass für das gesamte Board keine belastbaren Aussagen zu Erfolgsquote, Laufzeit, Nacharbeit oder Kosten existieren, und schlägt separat sowohl einen kleinen Eval-Korpus (`agent-pipeline-eval-baseline`) als auch einen eigenen Mess-/Datenschutz-Entscheid (`board-runtime-signal-measurement`) als Folgeintents vor, ohne sie bereits anzulegen. Dieser Intent macht daraus eine konkrete, klar abgegrenzte erste Version: nicht generische Pipeline-Telemetrie, sondern eine gezielte Vergleichsmessung mit einer expliziten Nullhypothese — dass ein einzelner Prompt an ein leistungsfähiges Modell (ohne Board, ohne Rollen-Pipeline) für denselben Intent mindestens ebenbürtig sein könnte. ## Ziel Für einen ausgewählten Intent lässt sich wiederholt messen und vergleichen: 1. **Wiederholte Board-Läufe desselben Intents** (gleicher Intent-Text, mehrere Durchläufe, ggf. über unterschiedliche Runtime-/Modell- Konfigurationen aus dem bestehenden Column-Config-Mechanismus, `board-builder-column-config.md`). 2. **Ein direkter Single-Prompt-Baseline-Lauf**: derselbe Intent-Text, einmal ohne Board/Pipeline direkt an ein festgelegtes starkes Modell gesendet, dessen Ergebnis (Diff/Antwort) genauso erfasst wie ein Board-Lauf. Verglichen werden pro Lauf mindestens: Qualität (Reviewentscheidung bzw. manuelle Einstufung beim Baseline-Lauf, da kein automatischer Reviewer), Geschwindigkeit (Wall-Clock von Start bis Endzustand), Kosten (Token- und/oder API-Kosten, soweit von der jeweiligen Runtime zuverlässig gemeldet) und Effizienz (Kosten bzw. Zeit pro erreichtem Erfolg, insbesondere über mehrere Wiederholungen desselben Intents hinweg zur Streuung/Varianz). ## Umfang - Neues, kleines, an den Intent-Slug gebundenes Log-Format (z. B. `docs/metrics/-runs.jsonl` oder ein `state.json`-Overlay-Feld `run_history`, Liste statt Einzelwert), das pro Lauf mindestens erfasst: Zeitstempel Start/Ende, Runtime/Modell, Iterationslimit, Endzustand/Reviewentscheidung, Commit-Hash bzw. Bericht, Token-/ Kostenwert falls verfügbar, sowie ein Feld `run_kind` ∈ {"board", "baseline_single_prompt"}. - Ein separater, expliziter Weg, einen Baseline-Lauf für einen bestehenden Intent-Slug anzulegen, ohne den normalen Board-Trigger zu durchlaufen — z. B. ein schlankes Skript, das den Intent-Text nimmt, ihn an ein festgelegtes Modell schickt und Antwort + Metadaten unter demselben `run_history`-Schema ablegt. Kein neuer Board-Spaltentyp dafür nötig. - Minimale Board-Anzeige: pro Karte eine kompakte Zusammenfassung "N Läufe, davon M Board / K Baseline, Erfolgsquote X%", keine vollständige Analytics-UI. - Auswahl eines kleinen, festen Vergleichs-Sets (2-3 reale, bereits bekannte Intents unterschiedlicher Größe) als Pilot statt sofort alle Intents zu instrumentieren. ## Ausgeschlossen - Keine automatische, fortlaufende Telemetrie für jeden Board-Lauf ohne gezielte Auswahl — reiner Opt-in-Pilot für die im Umfang genannten Testfälle. - Keine automatische Qualitätsbewertung/kein LLM-as-Judge für den Baseline-Lauf — die Einstufung bleibt vorerst manuell, analog zum bestehenden Review-Freitext. - Kein Dashboard/keine Visualisierung über die im Umfang genannte kompakte Zusammenfassung hinaus. - Keine Änderung an bestehenden Job-/Review-Abläufen — dieser Intent fügt nur zusätzliche Beobachtung hinzu, ändert kein Verhalten. - Kein Entscheid über Aufbewahrung/Datenschutz für dauerhafte, produktionsweite Telemetrie — das bleibt, wie im Research-Bericht benannt, ein separater Entscheid vor einer Ausweitung über den Pilot hinaus. ## Offene Risiken - Nicht jede Runtime meldet Token-/Kostenwerte zuverlässig — das Feld muss optional/nullable sein, nicht Voraussetzung für einen gültigen Log-Eintrag. - Ein einzelner Baseline-Lauf pro Intent hat keine statistische Aussage- kraft; ohne mehrere Wiederholungen bleibt der Vergleich anekdotisch — das Pilot-Set sollte deshalb mehrere Wiederholungen je Intent und Lauf-Art einplanen, nicht nur je einen Lauf. - Manuelle Qualitätseinstufung des Baseline-Laufs ist subjektiv und nicht direkt vergleichbar mit der automatisierten Reviewentscheidung eines Board-Laufs — im Bericht muss das als Limitation benannt werden, nicht als gleichwertige Metrik verkauft werden. - Kosten für zusätzliche Wiederholungsläufe (insbesondere mehrere Board-Durchläufe desselben Intents) sind selbst ein Tokenverbrauch, der gegen den Erkenntnisgewinn abzuwägen ist — Pilot bewusst klein halten. ## Erfolgskriterien - Für mindestens einen realen Intent liegen sowohl mehrere Board-Läufe als auch mindestens ein Single-Prompt-Baseline-Lauf im selben Log-Schema vor. - Die kompakte Board-Zusammenfassung zeigt Laufanzahl und Erfolgsquote ohne manuelles Nachschlagen in `state.json`. - Ein Mensch kann anhand der gesammelten Daten für den Pilot-Fall begründet einschätzen, ob die Board-Pipeline gegenüber einem direkten Prompt an ein starkes Modell einen Qualitäts-, Geschwindigkeits- oder Kostenvorteil bringt — auch wenn das Ergebnis "kein klarer Vorteil" ist.