Add ci_policy_documentation/README.md
This commit is contained in:
parent
eeedd2182f
commit
c2aa247123
1 changed files with 193 additions and 0 deletions
193
ci_policy_documentation/README.md
Normal file
193
ci_policy_documentation/README.md
Normal file
|
|
@ -0,0 +1,193 @@
|
||||||
|
# CI-Policy Dokumentation für Gate v0.1
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Definition der CI-Policy-Regeln und Entscheidungslogik für Gate v0.1 auf Basis der k-of-n Aggregation und Decision-Margin-Mechanismen.
|
||||||
|
|
||||||
|
**Problemstellung:** Vor Gate v0.1 führten unstabile Aggregationsentscheidungen (z. B. k=3-of-6) zu häufigen Flip-Flops. Ziel ist eine belastbare, überprüfbare Regelung der Entscheidungslogik.
|
||||||
|
|
||||||
|
**Ziele:**
|
||||||
|
- Standardisierte Entscheidung über PASS/WARN/FAIL in CI-Prozessen
|
||||||
|
- Nachvollziehbare Aggregationslogik mit reproduzierbarem Backtest
|
||||||
|
- Etablierung robuster Schwellenwerte zur Reduktion von Fehlalarmen
|
||||||
|
|
||||||
|
## Kontext & Hintergrund
|
||||||
|
|
||||||
|
Frozen-Runs #20–#29 mit Ausgabedaten wie mischfenster_p95, margin, flaky_flag und subset_flip_count.
|
||||||
|
|
||||||
|
**Gruppierung:**
|
||||||
|
- run_id
|
||||||
|
- pinned
|
||||||
|
|
||||||
|
**Trace-Metadaten / zusätzliche Tags:**
|
||||||
|
- pinned Zustand
|
||||||
|
- Metrik mischfenster_p95
|
||||||
|
- Subset-Stabilität (subset_flip_count)
|
||||||
|
|
||||||
|
**Domänenkontext:**
|
||||||
|
- CI-Gate-Entscheidungssystem
|
||||||
|
- Performance- und Stabilitätstests
|
||||||
|
|
||||||
|
**Outlier-Definition:**
|
||||||
|
- Methode: Decision-Margin-Threshold
|
||||||
|
- Beschreibung: Definiert eine Zone um den Schwellenwert, in der FAIL in WARN umgewandelt wird.
|
||||||
|
- Metrik: mischfenster_p95
|
||||||
|
|
||||||
|
**Motivation:**
|
||||||
|
- Reduktion von Fehlalarmen in automatisierten Evaluationsläufen
|
||||||
|
- Transparente Entscheidungsfindung basierend auf Backtest-Daten
|
||||||
|
- Klare Trennung zwischen Warn- und Fehlerzuständen
|
||||||
|
|
||||||
|
## Methode / Spezifikation
|
||||||
|
|
||||||
|
**Übersicht:**
|
||||||
|
- Verwendet k-of-n Aggregation für n=6 Subentscheidungen.
|
||||||
|
- Standardkonfiguration: k=5-of-6 gilt als stabil.
|
||||||
|
- Decision-Margin-Zone konvertiert knappe FAILs zu WARNs.
|
||||||
|
- Flaky-Flag kennzeichnet instabile Subsets mit hoher Flip-Rate.
|
||||||
|
|
||||||
|
**Algorithmen / Verfahren:**
|
||||||
|
- Berechne mischfenster_p95 pro Run.
|
||||||
|
- Aggregiere n=6 Resultate per k-of-n-Logik.
|
||||||
|
- Ermittle Decision-Margin basierend auf Schwellwert.
|
||||||
|
- Setze flaky_flag auf TRUE, wenn subset_flip_count > 0.
|
||||||
|
|
||||||
|
### Bootstrap-Übersicht
|
||||||
|
|
||||||
|
Kein Bootstrap-Verfahren im eigentlichen Sinne – Backtest erfolgt über existierende Frozen-Runs.
|
||||||
|
|
||||||
|
**Zielgrößen:**
|
||||||
|
- Stabilität der Gate-Entscheidung
|
||||||
|
- Minimierung von Flip-Flops
|
||||||
|
|
||||||
|
### Abgeleitete Effektgrößen
|
||||||
|
|
||||||
|
**Risk Difference (Differenz der Raten):**
|
||||||
|
- Definition: Differenzanteil von FAIL-Entscheidungen zwischen Konfigurationen (z. B. k=3 und k=5).
|
||||||
|
- Bootstrap: Backtest-basierte Beobachtung über Runs #20–#29, keine Resampling-Verfahren verwendet.
|
||||||
|
|
||||||
|
**Risk Ratio:**
|
||||||
|
- Definition: Verhältnis des Fehl-Alarms zwischen alten und neuen Gate-Einstellungen.
|
||||||
|
- Bootstrap: Berechnet aus beobachteten CSV-Aggregaten.
|
||||||
|
|
||||||
|
## Input / Output
|
||||||
|
|
||||||
|
### Input-Anforderungen
|
||||||
|
|
||||||
|
**Hardware:**
|
||||||
|
- Standard CI-Runner Hardware, keine Spezialhardware erforderlich
|
||||||
|
|
||||||
|
**Software:**
|
||||||
|
- Python >= 3.9
|
||||||
|
- CSV-Auswertung in Pandas optional
|
||||||
|
|
||||||
|
**Konfiguration:**
|
||||||
|
- Gate-Parameter: k=5, n=6
|
||||||
|
- Decision-Margin-Threshold definieren (experimentabhängig)
|
||||||
|
|
||||||
|
### Erwartete Rohdaten
|
||||||
|
|
||||||
|
**Felder pro Run:**
|
||||||
|
- run_id
|
||||||
|
- pinned
|
||||||
|
- mischfenster_p95
|
||||||
|
- decision
|
||||||
|
- margin
|
||||||
|
- flaky_flag
|
||||||
|
- subset_flip_count
|
||||||
|
|
||||||
|
**Formatbeispiele:**
|
||||||
|
- 24, true, 0.935, WARN, 0.012, false, 1
|
||||||
|
|
||||||
|
**Trace-Daten:**
|
||||||
|
- Format: CSV
|
||||||
|
- Hinweis: Keine neuen Messungen, ausschließlich Reanalyse bestehender Frozen-Runs.
|
||||||
|
|
||||||
|
### Analyse-Ausgaben
|
||||||
|
|
||||||
|
**Pro Gruppe / pro Governor:**
|
||||||
|
- Anteil von PASS/WARN/FAIL pro Run
|
||||||
|
- Stabilitätsindikator pro Aggregationsgruppe
|
||||||
|
|
||||||
|
**Vergleichsausgaben:**
|
||||||
|
- k=3-of-6 vs k=5-of-6
|
||||||
|
- Δ: Reduktion der Flip-Flop-Rate um ~X Prozentpunkte
|
||||||
|
- RR: Rückgang der Fehlalarme um Faktor Y
|
||||||
|
|
||||||
|
- Trace-Muster: Visualisierung von subset_flip_count vs. Decision-Margin zur Stabilitätsanalyse
|
||||||
|
|
||||||
|
## Workflow / Nutzung
|
||||||
|
|
||||||
|
**Analyse-Workflow:**
|
||||||
|
- Importiere Frozen-Run-Daten (#20–#29).
|
||||||
|
- Führe k-of-n Aggregation mit k=5, n=6 aus.
|
||||||
|
- Berechne Decision-Margin und flaky_flag.
|
||||||
|
- Erzeuge zusammenfassende CSV- und Debug-JSON-Dateien.
|
||||||
|
- Verifiziere Ergebnisse gegen bestehende Aggregationskonfigurationen (z. B. k=3).
|
||||||
|
|
||||||
|
### Trace-Template-Anforderungen
|
||||||
|
|
||||||
|
**Ziel:** Einheitlicher Vergleich über identische Run-Strukturen hinweg.
|
||||||
|
|
||||||
|
**Erforderliche Tags & Metadaten:**
|
||||||
|
- run_id
|
||||||
|
- pinned
|
||||||
|
- mischfenster_p95
|
||||||
|
|
||||||
|
**trace-cmd-Setup:**
|
||||||
|
- Nutze unveränderte Pipeline-Konfiguration.
|
||||||
|
- Keine zusätzlichen Measurement-Probes aktivieren.
|
||||||
|
|
||||||
|
**Run-Design für Contributors:**
|
||||||
|
- Ergänze Runs nur, wenn Freeze-Kriterien erfüllt sind.
|
||||||
|
- Dokumentiere Margin-Threshold-Werte im Git-Metadatenfeld.
|
||||||
|
|
||||||
|
## Interpretation & erwartete Ergebnisse
|
||||||
|
|
||||||
|
**Kernbefunde:**
|
||||||
|
- k=5-of-6 eliminiert instabile Flip-Flop-Verhalten fast vollständig.
|
||||||
|
- Decision-Margin verringert Fehlalarme ohne signifikante Sensitivitätseinbußen.
|
||||||
|
- Flakiness wird transparent markiert statt überdeckt.
|
||||||
|
|
||||||
|
**Implikationen für Experimente:**
|
||||||
|
- Standardisierung der k-of-n Aggregation im CI-System.
|
||||||
|
- Integration von WARN-Stufen zur kontrollierten Fehlertoleranz.
|
||||||
|
|
||||||
|
**Planungsziel:**
|
||||||
|
- Ziel: Reduktion fehlerhafter FAIL-Entscheidungen in der CI-Auswertung.
|
||||||
|
- Vorgehen:
|
||||||
|
- Einführung von Decision-Margin-Grenzen.
|
||||||
|
- Validierung über Backtest-Ergebnisse.
|
||||||
|
- Anwendung konsistenter Aggregationsparameter in zukünftigen Versionen.
|
||||||
|
|
||||||
|
## Limitationen & Fallstricke
|
||||||
|
|
||||||
|
**Datenbezogene Limitationen:**
|
||||||
|
- Begrenzte Stichprobe (nur Runs #20–#29).
|
||||||
|
- Keine neuen Messproben; mögliche Datenverzerrungen bleiben bestehen.
|
||||||
|
|
||||||
|
**Bootstrap-spezifische Limitationen:**
|
||||||
|
- Keine echte Bootstrap-Stichprobenbildung; Ergebnisse basieren auf beobachteten Werten.
|
||||||
|
|
||||||
|
**Kausalität & Generalisierbarkeit:**
|
||||||
|
- Ergebnisse gelten nur für identische Metriken und Run-Strukturen.
|
||||||
|
- Keine Generalisierung auf andere Gate-Signale ohne Revalidierung.
|
||||||
|
|
||||||
|
**Praktische Fallstricke:**
|
||||||
|
- Fehlende Dynamik bei Änderungen der Metrik mischfenster_p95.
|
||||||
|
- Decision-Margin kann bei stark schwankenden Runs Fehlinterpretationen erzeugen.
|
||||||
|
|
||||||
|
## Nächste Schritte & Erweiterungen
|
||||||
|
|
||||||
|
**Geplante Experimente:**
|
||||||
|
- Evaluation anderer k-Werte zur Stabilitätsanalyse unter variierenden Bedingungen.
|
||||||
|
|
||||||
|
**Analyseziele:**
|
||||||
|
- Umfassende Gegenüberstellung k=3 vs. k=5 mit Flip-Flop-Tabelle.
|
||||||
|
- Integration der CI-Reaktionsregeln direkt in das Reporting.
|
||||||
|
|
||||||
|
**Regression & Modellierung:**
|
||||||
|
- Aufbau eines Regressionsmodells zur Vorhersage von Flakiness basierend auf margin- und subset-Metriken.
|
||||||
|
|
||||||
|
**Community-Beiträge:**
|
||||||
|
- Bereitstellung der Backtest-CSV und CI-Policy-Definition zur Reproduktion durch andere Teammitglieder.
|
||||||
Loading…
Reference in a new issue