Add drift_report_md/README.md

drift_report_md/README.md

@@ -0,0 +1,171 @@
+# Drift-Report Markdown Artefakt für CI-Bewertung
+
+## Purpose
+
+Erzeugt menschenlesbare Drift-Berichte aus CI-Läufen mit Betriebsmetriken und Warnindikatoren.
+
+**Problemstellung:** Entwickler benötigen verständliche Drift-Indikatoren in CI-Reports, ohne manuelles Parsing von JSON-Daten.
+
+**Ziele:**
+- Klarer Überblick über aktuelle Driftlage pro Pipeline-Fenster
+- Transparente Darstellung von PASS, WARN, FAIL Status
+- Erkennung von Anomalien durch pinned Warnungen
+
+## Kontext & Hintergrund
+
+CI-Laufdaten mit PASS/WARN/FAIL Labels über ein gleitendes Fenster.
+
+**Gruppierung:**
+- Pipeline-Runs
+- zeitliches Rolling-Fenster
+
+**Trace-Metadaten / zusätzliche Tags:**
+- run_id
+- job_status
+- debug_json_presence
+
+**Domänenkontext:**
+- CI Monitoring
+- Drift Detection
+- Operational Reporting
+
+**Outlier-Definition:**
+- Methode: Threshold-basiert
+- Beschreibung: WARN-Quote > 30 % im aktuellen Fenster signalisiert Drift.
+- Metrik: warn_ratio
+
+**Motivation:**
+- Fehlerquellen in Model- oder Datenqualität früh erkennen
+- Fehlende Debug-JSONs sichtbar markieren statt still ignorieren
+- pinned Runs als Referenz stabil halten
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Report aggregiert Ergebnisse über ein konfiguriertes Fenster.
+- Parameter bestimmen Zählwerte und Schwellenbedingungen.
+- Markdown-Ausgabe betont kritische Kennzahlen fett.
+
+**Algorithmen / Verfahren:**
+- Berechne gleitendes Fenster von window_size Läufen.
+- Zähle PASS, WARN, FAIL Ereignisse.
+- Berechne warn_ratio = warn_count / window_size.
+- Markiere pinned_warn_fail_count separat.
+- Exportiere strukturierte Markdown-Datei drift_report.md.
+
+### Bootstrap-Übersicht
+
+**Zielgrößen:**
+### Resampling-Setup
+
+**Resampling-Schema:**
+**Konfidenzintervalle:**
+- Niveau: 0.95
+
+### Abgeleitete Effektgrößen
+
+### C-State-Kontrolle
+
+**Vorgehen:**
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+**Software:**
+- CI Runner mit Zugriff auf Artefakt-Speicher
+- Python oder Shell-basierte Laufumgebung
+
+**Konfiguration:**
+- window_size konfigurierbar
+- warn_ratio_threshold = 0.3
+- rerun_budget=1 optional
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- run_id
+- label
+- debug_json_available
+
+**Formatbeispiele:**
+- { 'run_id': 184, 'label': 'WARN', 'debug_json_available': false }
+
+**Trace-Daten:**
+- Format: JSON
+- Hinweis: drift_report.json dient als Eingabe für Markdown-Erzeugung
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+**Vergleichsausgaben:**
+
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Job im CI ausführen.
+- Daten aus den letzten window_size Läufen aggregieren.
+- generate_drift_report_md(window_size, pass_count, warn_count, fail_count, warn_ratio, pinned_warn_fail_count) aufrufen.
+- Artefakt drift_report.md und drift_report.json publizieren.
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Konsistentes Reporting über CI-Läufe hinweg.
+
+**Erforderliche Tags & Metadaten:**
+- run_id
+- pipeline_id
+- status_label
+- pinned_flag
+
+**trace-cmd-Setup:**
+- Sicherstellen, dass Job jedes Ergebnis im Artefaktpfad exportiert.
+
+**Run-Design für Contributors:**
+- Neue Experimente sollen window_size und Schwellen konfigurieren und Ergebnisse vergleichen.
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- WARN-Rate stabil unter Schwelle signalisiert Systemgesundheit.
+- pinned_warn_fail_count > 0 indiziert potenzielle Regression oder Labeling-Problem.
+- Fehlende Debug-Dateien erzeugen expliziten unknown-Eintrag.
+
+**Implikationen für Experimente:**
+- Rolling-Fenster-Anpassungen beeinflussen Sensitivität.
+- Drift-Warnschwelle kann CI-Stabilität vs. Reaktivität steuern.
+
+**Planungsziel:**
+- Ziel: Live-Monitoring der Drift-Stabilität in CI-Umgebung.
+- Vorgehen:
+  - Messung über feste Fenstergrößen
+  - Erfassen von pinned States zur Drift-Bewertung
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Fehlende Debug-JSONs können Statistik verzerren.
+- Geringe Fenstergröße reduziert Aussagekraft.
+
+**Kausalität & Generalisierbarkeit:**
+- CI-spezifische Ergebnisse nicht direkt auf Produktionssysteme übertragbar.
+
+**Praktische Fallstricke:**
+- Zu häufige WARNs können Alarmmüdigkeit verursachen.
+- Nicht-persistent gespeicherte Artefakte erschweren Nachvollziehbarkeit.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Vergleich von N=10 vs. N=20 Fenstern auf identischem Datensatz.
+- Einführung von Auto-Rerun (rerun_budget=1) zur Evaluierung.
+
+**Analyseziele:**
+- Langzeitstabilität der Drift-Warnung untersuchen.
+
+**Regression & Modellierung:**
+- Zusammenhang zwischen pinned Warnungen und Datenquellendrift analysieren.
+
+**Community-Beiträge:**
+- Feedback zu Report-Darstellung (Markdown-Layout, Tabellenstruktur) einholen.