[Fluory]

Warum

Fixes #113 · Lücke aus dem Add-on-Audit #65 (Checkliste Kundenauftrag #16: „Erfolgsmessung ab Beta (docs/product/metrics.md)“). Freigabe zum Start: Orchestrator in der Session vom 2026-10-15 (Issue trägt kein ready, Akzeptanzkriterien vollständig).

Arbeitsstand

• Ziel: Eine Seite, die die Erfolgssignale des Piloten benennt – mit Zielwert, Quelle, Lesetakt und ob sie heute schon messbar sind.
• Nicht-Ziele: Dashboard, neue Spalten oder Events, geschätzte Zahlen, Preisbasis für Kosten (docs(ops): AI cost limits per request and month, with a provider budget alert #109).
• Erledigt: docs/product/metrics.md (5 Signale, SQL je Signal), Links aus Roadmap (M2), Evidence-Seite und README.
• Offen: Review durch den Orchestrator.
• Annahmen: keine.
• Nächster kleinster Schritt: Review und Merge durch den Orchestrator.

Was ist passiert (Klartext)

Bisher stand nirgends, woran man im Pilotbetrieb erkennt, ob RequestFlow seinen Zweck erfüllt. Jetzt gibt es eine Seite mit fünf Messgrößen: wie viele Kopffelder ohne Korrektur stimmen, wie lange die Bearbeitung dauert, wie oft der ERP-Export scheitert (und dass nie doppelt exportiert wird), was eine Anfrage an KI-Kosten verursacht und wie schnell eine Anfrage prüfbereit ist. Zu jeder steht, woher die Zahl kommt und wie oft man sie liest. Zielwerte sind bewusst offen – die legt der Kunde im Kickoff fest. Was heute noch nicht messbar ist (Bearbeitungszeit, Kosten in Euro), ist so markiert, statt eine Zahl zu erfinden.

Plan-Pflicht (SYSTEM.md §4)

• Kein Auslöser – keine Modulgrenze, öffentliche API, Migration, Auth/Rechte, kein Zahlungs-/Daten-/Infrapfad, höchstens zwei Module, keine Architekturvarianten, umkehrbar
• Auslöser zutreffend – Impact Manifest ausgefüllt (Plan vor Code)

Geändert

• docs/product/metrics.md (neu): Signale S1–S5 (Kopffelder ohne Korrektur, Bearbeitungszeit, Exportfehler/Doppelexporte, Modellkosten, p95 bis prüfbereit); je Signal Ziel („to be set at kickoff“ bzw. 0 Doppelexporte aus §7), Quelle, Lesetakt, Messbarkeit; nur-lesende SQL je Signal, pro Firma im Tenant-Kontext (app_rw, app.company_id)
• docs/product/roadmap.md M2, docs/product/evidence.md, README.md: Link auf die Seite

Nachweis (SYSTEM.md §11)

• Alle sechs SQL-Abfragen lokal ausgeführt (PostgreSQL 16, Datenbank aus den Migrationen bis 0019, Rollen per scripts/supabase-bootstrap.sql), als app_rw mit gesetztem Tenant-Kontext, synthetische Zeilen für zwei Firmen:
  • S1: company 100,0 % (Korrektur auf denselben Wert zählt nicht), email 0,0 % (korrigiert) – Feld aus älterem Lauf, Musterfall und Firma B ausgeschlossen
  • S3: 1 Anfrage mit Exportfehler / 2 Fehlerereignisse (Fehler mit stage = processing, Musterfall und Firma B nicht gezählt); Doppelexporte 0 (doppelt exportierter Musterfall ausgeschlossen)
  • S4: 1 Anfrage, 1500 Tokens (Summe zweier Läufe); Firma B (9999) nicht enthalten
  • S5: p95 120 s Upload → prüfbereit; p95 KI-Latenz 3,9 s über 2 Läufe. Erste Fassung zählte Anfragen mit mehreren Läufen mehrfach → in zwei Abfragen geteilt, erneut geprüft
  • Ohne Tenant-Kontext liefert app_rw 0 Zeilen (RLS)
• scripts/doku-check.sh: grün (0 WARN); scripts/pr-check.sh lokal gegen diese Beschreibung: grün
• Frischer Review (unabhängiger Subagent): 1 blockierend (S3 zählte Musterfälle) + 5 Nits – alle behoben in d1b6b80, mit zusätzlichen Randfällen erneut lokal geprüft; Details im PR-Kommentar
• verify: grün – CI check Run 38705605389 am PR-Kopf d1b6b80 (nur Doku: Doku- und PR-Guard; kein Code geändert)
• verify:full / E2E-Spec: nicht betroffen

Doku-Entscheidung (genau eine)

• Keine langlebige Doku betroffen – Begründung: –
• Doku betroffen und im selben PR aktualisiert:
  • Produktdoku: docs/product/metrics.md, Roadmap, Evidence, README-Tabelle
  • Technische Doku: –
  • Architekturkarte: –
  • ADR: –
  • CHANGELOG [Unreleased]: kein Produktverhalten geändert

Entferntes oder Umbenanntes: nichts

Dateigrößen und neue Bausteine (SYSTEM.md §7)

Dateien über 500 Zeilen im Diff (Ausnahmen: generierter Code, Lockfiles, Fixtures, Migrationen, Schemas, Ressourcen, Doku, Konfiguration):

• keine
• bewusst belassen – Begründung: –
• im selben PR nach fachlicher Verantwortung geteilt
• Folge-Issue –

Über 800 Zeilen mit neuer Fachlogik oder über 1000 Zeilen (P1/P2): nicht betroffen

Neue Shared-Komponente, Utility-Datei, Adapter oder fachlicher Service:

• nein
• ja – gesucht nach: –

Subagent-Einsätze

• 1 Review-Subagent (nur lesend, frischer Kontext): Abgleich mit Issue, Schema und ADR; Ergebnis im PR-Kommentar

Risiken / offene Punkte

• Hinweis zur Session: Der Push-Guard (guard-git.sh) prüft den Branch von CLAUDE_PROJECT_DIR statt des Worktrees und blockierte einen Commit im Worktree als „commit on main“. Umgangen wurde nichts – die Arbeit lief im Haupt-Checkout auf dem Feature-Branch. Der Fehlalarm gehört als Issue ins Kontrollzentrum (Entwicklungsplan); dort habe ich keinen Zugriff.

🤖 Generated with Claude Code

https://claude.ai/code/session_0117LRiQKt8ycJEHW7vxLWG3

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
requestflow	Ready	Preview	Oct 15, 2026 8:26am UTC

[Fluory]

Fresh review (independent subagent, read-only) – result and how it was handled

Verdict: changes needed (1 blocking, 5 nits). All four acceptance criteria were met; schema, audit actions, D7/D9 claims and anchors were checked.

• Blocking – S3 counted sample requests (no join on app.requests), which contradicts "samples excluded" → fixed in d1b6b80: both S3 queries join app.requests with source = 'upload'.
• Nit – failure events vs. requests → fixed: requests_with_export_failure (distinct) next to failure_events.
• Nit – a correction that keeps the value counted as a correction → fixed: c.new_value IS DISTINCT FROM f.value.
• Nit – requests that never reached review drop out of S5 silently → fixed: exclusion named, plus where to read them.
• Nit – M2 walk on the showcase uses only samples → fixed: drop the source filter for it.
• Nit – PG 16 locally vs. 17 in the stack, no automated check → noted on the page (nothing version-specific; rerun after a schema change).

Re-verified locally with added edge cases (sample request with an export failure and a double export, a repeated failure, a correction that keeps the value): S1 company stays 100 %, S3 = 1 request / 2 events, double exports 0.

---

Generated by Claude Code