# 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.