Add delta_cases_analyzer/README.md

delta_cases_analyzer/README.md

@@ -0,0 +1,218 @@
+# Analyse von Unknown-Fällen in delta_cases.csv
+
+## Purpose
+
+Dokumentation zur quantitativen Analyse und Differenzierung von Unknown-Fällen in CI-Gate-Prozessen anhand von delta_cases.csv.
+
+**Problemstellung:** Unknown-Fälle verfälschen Gate-Analysen, wenn Artefaktmangel und Contract-Verletzung nicht getrennt betrachtet werden.
+
+**Ziele:**
+- Unknown-Fälle in CI-Artefakten kategorisieren
+- Artefaktmängel von echten inhaltlichen Regressionsursachen trennen
+- Stabilität von Gate v1 durch statistische Evidenz bewerten
+
+## Kontext & Hintergrund
+
+CSV-Datei delta_cases.csv mit Falltransitionsdaten pro Stratum in CI-Prozessen.
+
+**Gruppierung:**
+- Stratum A
+- Stratum B
+- Stratum C
+
+**Trace-Metadaten / zusätzliche Tags:**
+- new_status
+- unknown_reason
+- pipeline_output_status
+
+**Domänenkontext:**
+- Continuous Integration (CI)
+- Automatisierte Gate-Entscheidungen
+- Regressionserkennung
+
+**Outlier-Definition:**
+- Methode: Change-Rate-Delta
+- Beschreibung: Erkennung signifikanter Zuwächse in PASS→Unknown Übergängen pro Stratum.
+- Metrik: Unknown-Rate-Delta
+
+**Motivation:**
+- Erhöhung der Entscheidungssicherheit bei CI-Gates
+- Reduktion von Fehlbeurteilungen durch Artefaktmängel
+- Schaffung reproduzierbarer Analysen mittels Python-Skripten
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Tägliche Erfassung des delta_cases.csv Snapshots über einen siebentägigen Beobachtungszeitraum.
+- Filtern und Aggregieren von Fällen mit Statuswechsel zu Unknown.
+- Kategorisierung der Unknown-Ursachen nach Typ (Artefaktmangel vs. Contract-Verletzung).
+
+**Algorithmen / Verfahren:**
+- Iteriere über delta_cases.csv mittels csv.DictReader.
+- Zähle Unknown-Fälle nach unknown_reason über collections.Counter.
+- Ableitung einer Unknown-Whitelist für bekannte Artefaktmängel.
+
+### Bootstrap-Übersicht
+
+Bootstrap-Resampling ist hier nicht angewandt, vorgesehen für spätere Stabilitätsbewertungen pro Unknown-Typ.
+
+**Zielgrößen:**
+- Unknown-Rate-Stabilität
+- Konfidenzintervall des Unknown-Delta pro Stratum
+
+### Resampling-Setup
+
+- Stratum A
+- Stratum B
+- Stratum C
+
+**Stichprobeneinheit:** Testfall pro CI-Run
+
+**Resampling-Schema:**
+- Fixed-Format pro Snapshot
+- 7-Tage-Sequenz für zeitliche Differenzen
+
+**Konfidenzintervalle:**
+- Niveau: 0.95
+- Typ: bootstrap
+- Ableitung: Empirische Verteilung der Unknown-Anteile
+
+### Abgeleitete Effektgrößen
+
+**Risk Difference (Differenz der Raten):**
+- Definition: Differenz der Unknown-Raten zwischen Tagen oder Strata.
+- Bootstrap: CI aus wiederholtem Resampling derselben Gruppen
+
+**Risk Ratio:**
+- Definition: Verhältnis der Wahrscheinlichkeit Unknown vs. PASS in verschiedenen Strata.
+- Bootstrap: Verteilungsbasierte CI-Schätzung mit 95%-Level
+
+### C-State-Kontrolle
+
+**Ziel:** Sicherstellen, dass Infrastructure-Induced Unknowns (Artefaktfehler) nicht als logische Regressionsfälle interpretiert werden.
+
+**Vorgehen:**
+- Separate Whitelist für identifizierte Artefaktmängel pflegen
+- Nur Contract-Verletzungen als echte Regressionsindikatoren zählen
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- Standard CI-Umgebung mit Python 3
+
+**Software:**
+- Python 3.8+
+- csv-Modul (Standardbibliothek)
+
+**Konfiguration:**
+- delta_cases.csv im Root-Log-Verzeichnis pro Tag
+- unknown_whitelist.json für bekannte Artefaktmängel
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- case_id
+- old_status
+- new_status
+- unknown_reason
+- stratum
+- timestamp
+
+**Formatbeispiele:**
+- 00123, PASS, Unknown, MissingOutputFile, A, 2024-02-11T09:23Z
+
+**Trace-Daten:**
+- Format: CSV-Tabellenstruktur
+- Hinweis: Jede Zeile entspricht einem Testfallübergang im CI-Prozess
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- Anzahl Unknown pro Stratum
+- Verteilung der unknown_reason Kategorien
+
+**Vergleichsausgaben:**
+- Tag1_StratumA vs Tag2_StratumA
+  - Δ: Δ Unknown = +x %
+  - CI(Δ): 95%-CI aus Resampling
+  - RR: RR Unknown(T2/T1)
+  - CI(RR): 95%-CI RR-Schätzung
+
+- C-State-Korrelation: Analyse der Unknown-Auftritte in Relation zu Pipeline-/Infrastructure-Logs
+- Trace-Muster: Zeitliche Muster der Unknown-Bildung über sieben Tage
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Erstelle täglichen CI-Snapshot im festen delta_cases.csv Format.
+- Führe Python-Skript zur Zählung der Unknown-Ursachen aus.
+- Protokolliere Resultate als stabile Metrik im Logbook.
+- Pflege unknown_whitelist.json manuell für sichere Artefaktmängel.
+- Vermeide Regeländerungen während der Beobachtungsperiode.
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Reproduzierbare Unknown-Erfassung über konsistente CSV-Struktur.
+
+**Erforderliche Tags & Metadaten:**
+- stratum
+- new_status
+- unknown_reason
+
+**trace-cmd-Setup:**
+- delta_cases.csv täglich exportieren
+- keine automatischen Statusänderungen im Beobachtungszeitraum
+
+**Run-Design für Contributors:**
+- Beobachtungsläufe über 7 Tage mit identischer Konfiguration
+- Trennung von funktionalen und Infrastrukturfehlern
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Unknown-Fälle bestehen aus mindestens zwei Hauptursachen: Artefaktmangel und Contract-Verletzung.
+- PASS→Unknown Delta in Stratum A weist auf datenbedingte Instabilität hin.
+- Korrekte Trennung erhöht Präzision der Gate-Entscheidung signifikant.
+
+**Implikationen für Experimente:**
+- Unknown-Gate-Fälle müssen kategorisiert werden, bevor sie als Stabilitätsindikator gelten.
+- Ergebnisse bilden Grundlage für künftige automatisierte Whitelisting-Prozesse.
+
+**Planungsziel:**
+- Ziel: Stabile, datengetriebene Gate-Entscheidung ohne Fehlklassifikationen.
+- Vorgehen:
+  - Langzeitbeobachtung der Unknown-Entwicklung
+  - Schrittweise Einbindung von Bootstrap-Analyse zur Varianzschätzung
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Fehlende oder inkonsistente unknown_reason Werte erschweren Klassifikation.
+- CSV-Strukturfehler können Zählungen verfälschen.
+
+**Bootstrap-spezifische Limitationen:**
+- Noch keine Implementierung; spätere Anwendung erfordert genügend Datenpunkte pro Stratum.
+
+**Kausalität & Generalisierbarkeit:**
+- Beobachtung einzelner Pipelines liefert keine generalisierbaren Aussagen über andere Projekte.
+
+**Praktische Fallstricke:**
+- Zu häufige Anpassung der Whitelist unterminiert Vergleichbarkeit.
+- Vermischung technischer und fachlicher Ursachen verfälscht Trenddaten.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Tag-2 bis Tag-7 Auswertung der Unknown-Typen zur Stabilitätsprüfung.
+
+**Analyseziele:**
+- Unknown-Rate-Trendanalyse über Zeit
+- Bootstrap-basierte Unsicherheitsabschätzung
+
+**Regression & Modellierung:**
+- Entwicklung eines einfachen Regressionsmodells zur Unknown-Prädiktion
+
+**Community-Beiträge:**
+- Best-Practices für Stable-Gate-Metriken in CI-Pipelines teilen