# 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