nixos-config/docs/intent/board-intent-run-metrics-baseline.md

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.htmls appendMetricsBadge(). Details, Feldnamen und exakte Aufrufweise stehen in README.mds 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/<slug>-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.