diff --git a/decision_table/README.md b/decision_table/README.md new file mode 100644 index 0000000..f1c3a68 --- /dev/null +++ b/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