fae170e9ad
- board.html: a card whose parent_id resolves to an existing card is rendered nested inside that parent instead of as a detached top-level column card, and stays fully draggable there (docs/intent/board-nested-child-intents.md). - metrics.py (new) + hooks in worker.py/completion_watcher.py: opt-in run_history logging gated by BOARD_METRICS_SLUGS, exposed as a compact per-card summary via trigger.py/board.html. - metrics_baseline.py (new) + worker.run_baseline(): manual CLI to send an intent straight to a model with no board pipeline, no repo access, as the comparison point for the run-metrics pilot (docs/intent/board-intent-run-metrics-baseline.md). - 16 new tests, 148/148 total passing. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UeyiEf4XmoPgxkarAXamGe
126 lines
6.4 KiB
Markdown
126 lines
6.4 KiB
Markdown
# 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/<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.
|