Add decision_table/README.md

decision_table/README.md

@@ -0,0 +1,220 @@
+# 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