# Decision-Tabelle zur Klassifizierung von Unknowns und Rerun-Effekt-Analyse (Policy v1.1)

## Purpose

Dokumentiert die Entscheidungstabelle für Unknown-Klassifikationen in der CI und spezifiziert die Rerun-Regeln gemäß Audit-Ergebnissen.

**Problemstellung:** Fehlende Systematik zur Behandlung und Klassifikation von Unknown-Runs führte zu inkonsistenter CI-Analyse und uneinheitlichen Ergebnissen.

**Ziele:**
- Konsistente Klassifizierung bisher unklarer CI-Ergebnisse (Unknowns)
- Definition von klaren Actions (PASS, WARN, FAIL) pro Unknown-Klasse
- Quantitative Bewertung des Rerun-Effekts zur Policy-Ableitung

## Kontext & Hintergrund

audit.csv mit N=112 Run-Einträgen, enthält Protokolle und Diagnoseinformationen zu CI-Runs.

**Gruppierung:**
- pinned
- unpinned

**Trace-Metadaten / zusätzliche Tags:**
- Stratum-Information für Effektanalyse
- Labels für CI-Status und Fehlerursachen

**Domänenkontext:**
- Continuous Integration
- Audit-basierte Klassifikation
- CI-Automatisierung

**Outlier-Definition:**
- Methode: Empirische Klassifikation aus Audit-Daten
- Beschreibung: Unknown-Runs gelten als Abweichungen, wenn Diagnose- oder Contract-Struktur unvollständig oder fehlerhaft ist.
- Metrik: Run-Status versus erwartete Klassifikationsparameter

**Motivation:**
- Bereinigung der Kategorie 'Unknown' in der CI-Auswertung
- Vermeidung von Fehlinterpretationen bei Rerun-Analysen
- Herstellung automatisierter Reproduzierbarkeit der Entscheidungen

## Methode / Spezifikation

**Übersicht:**
- Analyse von N=112 CI-Runs im audit.csv.
- Klassifikation aller Unknowns in vier Ursachenklassen.
- Zuordnung einer eindeutigen CI-Action pro Klasse.
- Bewertung des Rerun-Effekts auf Entscheidungsänderungen nach pinned/unpinned-Stratum.

**Algorithmen / Verfahren:**
- Tabellarische Klassifikation: Zuordnung von Actions und Labels basierend auf Ursache.
- Audit-basierte Aggregation des Rerun-Effekts über Helps, Shifts, Hurts.
- Policy-Ableitung: Rerun-Budget nur bei unpinned wirksam, Exklusion bei Contract- oder Artefakt-Fehlern.

### Bootstrap-Übersicht

Resampling-basierte Stabilisierung geplanter Schwellenwerte (warn_rate, unknown_rate).

**Zielgrößen:**
- WARN-Anteil
- Unknown-Anteil je Stratum

### Resampling-Setup

- pinned
- unpinned

**Stichprobeneinheit:** CI-Run

**Resampling-Schema:**
- Bootstrap mit Wiederholung zur Schätzung der Perzentil-basierten Schwellen

**Konfidenzintervalle:**
- Niveau: 0.95
- Typ: Perzentil-Konfidenzintervall
- Ableitung: Percentile bootstrap

### Abgeleitete Effektgrößen

**Risk Difference (Differenz der Raten):**
- Definition: Differenz der Häufigkeiten von Helps/ Hurts zwischen Strata.
- Bootstrap: Verwendung für Vertrauensintervalle der Rerun-Effekt-Schätzung.

**Risk Ratio:**
- Definition: Quotient der Helps-Rate zwischen unpinned und pinned Runs.
- Bootstrap: Resampling zur Unsicherheitsabschätzung der Risikoverhältnisse.

### C-State-Kontrolle

**Ziel:** Vermeidung von Messverzerrungen durch Systemzustände während Audit-Erhebung.

**Vorgehen:**
- Paarweise Analyse nach pinned/unpinned
- Standardisierung des Zeitraums pro Run

## Input / Output

### Input-Anforderungen

**Hardware:**
- Standard-CI-Infrastruktur ohne spezielle Hardwareanforderungen

**Software:**
- CI-System mit Log- und Trace-Export
- Audit-Tooling für CSV-Analyse

**Konfiguration:**
- aktive Trennung zwischen pinned und unpinned Runs
- Audit-Skript konfiguriert für Unknown-Erkennung

### Erwartete Rohdaten

**Felder pro Run:**
- run_id
- status
- artifact_presence
- contract_status
- parse_status
- pinned_flag

**Formatbeispiele:**
- 11234, UNKNOWN, missing, ok, fail, unpinned

**Trace-Daten:**
- Format: CSV/JSON
- Hinweis: Muss pro Run Log- und Analyse-Metadaten enthalten.

### Analyse-Ausgaben

**Pro Gruppe / pro Governor:**
- Helps-Quote
- Shifts-Quote
- Hurts-Quote pro Stratum

**Vergleichsausgaben:**
- unpinned vs pinned
  - Δ: Helps-Differenz in Prozentpunkten
  - CI(Δ): 95%-CI via Bootstrap
  - RR: Helps_unpinned / Helps_pinned
  - CI(RR): 95%-CI via Bootstrap
  - Tests: Signifikanztest optional

- C-State-Korrelation: Korrelation CI-Latenz vs. Klassifikationsfehler
- Trace-Muster: Häufige Unknown-Artefaktmuster nach Fehlerklasse

## Workflow / Nutzung

**Analyse-Workflow:**
- Audit-Daten einlesen
- Runs nach Unknown-Klasse gruppieren
- Decision-Tabelle anwenden: Klasse -> PASS/WARN/FAIL
- Rerun-Auswertung getrennt nach pinned/unpinned durchführen
- report.csv mit aktualisierten Klassifikationen erzeugen

### Trace-Template-Anforderungen

**Ziel:** Standardisierte Erfassung von Unknown-Ursachen zur Automatisierbarkeit der Policy-Anwendung.

**Erforderliche Tags & Metadaten:**
- run_id
- pinned_flag
- error_type
- contract_status
- rerun_count

**trace-cmd-Setup:**
- trace-cmd collect --metadata error_type,pinned_flag

**Run-Design für Contributors:**
- Min. 30 Runs pro Stratum zur statistischen Bewertung.

## Interpretation & erwartete Ergebnisse

**Kernbefunde:**
- Unknowns lassen sich in vier stabile Fehlerklassen mit klaren Actions einteilen.
- Rerun bringt bei unpinned Runs signifikante Verbesserung (Helps)
- Bei pinned Runs sind Reruns ineffektiv; meist nur Metrikverschiebungen (Shifts).

**Implikationen für Experimente:**
- Policy v1.1 nutzt Rerun nur als Tie-Breaker bei unpinned.
- Unvollständige Artefakte und Contract-Verstöße erzeugen immer WARN bzw. FAIL ohne Rerun-Korrektur.

**Planungsziel:**
- Ziel: Quantitative Ableitung robuster Warn- und Unknown-Schwellenwerte.
- Vorgehen:
  - Perzentil-basierte Schätzung der warn_rate und unknown_rate pro Stratum
  - Bootstrap-Verifikation der Stabilität.

## Limitationen & Fallstricke

**Datenbezogene Limitationen:**
- N=112 begrenzte Stichprobe, Risk-of-Overfitting in Schwellenableitung

**Bootstrap-spezifische Limitationen:**
- Stabile Konfidenzintervalle erfordern ≥1000 Resamples pro Stratum

**Kausalität & Generalisierbarkeit:**
- Rerun-Effekt gilt nur innerhalb auditierter Umgebung
- Keine Generalisierung auf andere CI-Systeme ohne Nachprüfung

**Praktische Fallstricke:**
- Fehlende oder falsch gelabelte Runs stören Unknown-Detektion
- Nicht alle Parser-Fehler sind deterministisch reproduzierbar

## Nächste Schritte & Erweiterungen

**Geplante Experimente:**
- Erweiterung des Audit-Datensatzes auf ≥500 Runs
- Validierung der Decision-Tabelle gegen neue CI-Versionen

**Analyseziele:**
- Kalibrierung von warn_rate und unknown_rate via Bootstrap-Perzentile
- Sensitivitätsanalyse nach Artefakt-Typ

**Regression & Modellierung:**
- Einführung logit-basierten Modells zur Unknown-Vorhersage
- Simulation des Rerun-Nutzens pro Klasse

**Community-Beiträge:**
- Veröffentlichung der Decision-Tabelle als YAML für Policy-v1.1-Replikation
- Einbindung in CI-Beobachtungs-Tooling von Mika Code Lab