---
name: av-eval-calibrator
description: Meta-Skill des AI-Visibility-Gap-Assessments (frueher ARD-Readiness-Audit). Bewertet nach JEDEM Audit-Lauf die Outputs der 8 Phasen-Skills anhand gratis abfallender Ground-Truth-Signale, generiert über die Claude-Subscription verbesserte Prompt-Varianten und entscheidet — Modus c — über Auto-Übernahme (nur bei gemessenem A/B-Gewinn) oder Change-Board-Vorschlag. Nutzen, wenn ein Audit gelaufen ist oder die Skill-Qualität geprüft/optimiert werden soll.
---

# av-eval-calibrator (Meta)

Der Selbstoptimierungs-Motor des Audits. Jeder Audit-Lauf wird zum
Eval-Datensatz — **ohne menschlichen Bewerter**, weil messbare Signale gratis
abfallen. Nach dem Lauf prüft der Calibrator jede Phase und schärft sie nach.

## Wann nutzen
- Automatisch nach jedem Audit (verdrahtet in `run_and_publish.py → run_calibrator`).
- Manuell, wenn Frank fragt „wie gut sind die Audit-Skills / optimiere sie".
- Vor einer Batch-/Gruppen-Auswertung, um den Stand der Skills zu sehen.

## Code & Daten
- Motor: `~/audit-app/ai-visibility-audit/av_calibrator.py`
- Eval-Datensatz (Replay-Quelle): `~/audit-app/data/skill-runs.jsonl`
- Snapshot (Seite/Admin): `~/audit-site/data/skills-eval.json`
- DB: `audit_skill_runs` (Läufe), `audit_skill_proposals` (Vorschläge)
- Prompt-Versionen: `~/audit-app/prompts/<skill>.active.txt` + `versions/<skill>/vNN.txt`

## Der Loop (3 Schritte)
1. **Aggregieren** — rollender Eval-Score (0..1, letzte 8 Läufe) je Skill,
   Trend, n_runs. Schreibt den Snapshot.
2. **Optimieren** — nur Skills **unter Ziel** (`TARGET=0.75`) und mit
   `n_runs ≥ 2`:
   - Variante über die **Subscription** (`claude -p`) generieren. Harte
     Invariante: identische `{platzhalter}` und identisches Ausgabeformat,
     sonst wird die Variante verworfen.
   - Variante als `versions/<skill>/vNN.txt` mit `#v:`-Marke ablegen.
3. **Entscheiden (Modus c)**:
   - **Messbare Skills** (`av-search-framing`, `av-prompt-designer`): echtes
     **Live-A/B** auf einem Probe-Set. Schlägt die Variante die Baseline um
     `MARGIN=0.05` → **Auto-Apply** (`prompt_store.promote`, alte Version
     archiviert, Audit-Trail). Sonst → Vorschlag `open`.
   - **Nicht billig messbare Skills** (`av-profiler`, `av-website-scorer`,
     `av-gap-strategist`): Variante geht **nur als Vorschlag** aufs
     Change-Board — ehrlich, kein Auto-Apply ohne gemessenen Beweis.
   - **Logik-Skills** (`av-mention-detector`, `av-benchmark-analyst`,
     `av-report-narrator`): kein LLM-Prompt → werden bewertet, aber nicht
     automatisch mutiert (Verbesserung = Code-Änderung, Vorschlag an Frank).

## Eval-Signale (gratis Ground-Truth)
| Skill | Signal | Idee |
|---|---|---|
| av-profiler | competitor_hit_rate | Tauchten die vermuteten Wettbewerber real auf? |
| av-prompt-designer | signal_yield × journey_coverage | Lieferten die Prompts Nennungen über alle Phasen? |
| av-search-framing | parseable_sources_rate | Anteil Antworten mit auswertbarer Quellen-Liste |
| av-mention-detector | consistency | Übereinstimmung mit striktem Wortgrenzen-Recheck |
| av-website-scorer | plausibility | Passt der Score zu has_jsonld/schema/FAQ/author? |
| av-gap-strategist | gap_coverage | Adressieren Maßnahmen die größten Lücken? |
| av-benchmark-analyst | field_coverage | Achsen mit Wettbewerber-Daten |
| av-report-narrator | completeness | Report gespeichert + Maßnahmen enthalten |

## Sicherheits-Garantien
- Der Calibrator läuft gekapselt (Subprozess, Subscription, kein API-Key) und
  darf **das Audit/den Publish nie kippen**.
- Auto-Apply NUR mit gemessenem A/B-Vorsprung — keine „Vibe"-Promotion.
- Jede Promotion/Vorschlag landet in `audit_skill_proposals` (Audit-Trail) und
  als Telegram-Ping an Frank.
- Manuell: `python av_calibrator.py` (voll) · `--aggregate-only` (nur Scores).

## Verwandte Skills
`skill-creator` (Eval/Benchmark-Methodik), `s2-enhance-skill`/`s3-review-skill`
(Lifecycle), die 8 Phasen-Skills `av-*`.