---
name: av-report-narrator
description: Letzte Phase des KI-Sichtbarkeits-Gap-Assessments (frueher ARD-Audit) — rendert die Audit-Ergebnisse zu einem lesbaren HTML-Report im Holocron-Stil (Spiderdiagramm, Soll-Ist-Lücken, priorisierte Maßnahmen, Projektion).
---

> **EVN:** Stellt die Kette dar: Eigenschaften (7 Dimensionen) → Vorteil **Sichtbarkeit** (OVI/AVI/Overall) → Nutzen **Auffindbarkeit**.

# av-report-narrator

Letzte Phase der Audit-Pipeline. Verwandelt die gesammelten Audit-Ergebnisse in
einen lesbaren HTML-Report im Holocron-Stil — die Bühne, auf der alle vorherigen
Phasen sichtbar werden.

## Wann nutzen

Am Ende eines KI-Sichtbarkeits-Gap-Assessments, wenn alle Achsen-Scores und
Maßnahmen vorliegen und ein präsentierbarer Report entstehen soll. Der Report
zeigt (aktuelles Layout — kein Zukunfts-Soll-Polygon und keine Umsetzungs-Projektion):

- **Ergebnis-Kacheln** — die Kernzahlen auf einen Blick, je Kachel mit
  Peer-Median-/Leader-Einordnung und Confidence.
- **Radar über die 7 Kern-Dimensionen** + optionales **Agentic-Modul
  (Knowledge-Catalog)** — das Modul wird als Zusatz ausgewiesen, nicht als
  achte Standard-Achse verkauft.
- **Zwei Linsen — OVI und AVI**: klassische Google-Suche (OVI) und KI-Suche
  (AVI). Das **AVI-Referenzpolygon ist das eigene OVI-heute** — der Vergleich
  läuft gegen den eigenen Ist-Zustand, nicht gegen ein Zukunfts-Soll.
- **Peer-Median + Leader-Overlay** je Achse (Median der Wettbewerber, Leader =
  höchster Wert derselben Tabelle inkl. Subjekt) — kein Soll-Polygon.
- **Prioritätenmatrix** — Priority Score (y) × Aufwand (x); Quick Wins zuerst,
  mit Aufwand und Quick-Win-Score.
- **Datierte Wette/Hypothese** („Die Wette dieses Assessments") — nur bei einer
  Lücke ≥ 5 Punkten, falsifizierbar formuliert und beim Re-Audit offen als
  gewonnen/verloren ausgewiesen. Keine Ergebnis-Garantie.
- **Gray-out-Achsen**: Achsen, die in einer Linse nicht zählen, werden grau mit
  Rohwert gezeigt statt auf 0 zu kollabieren. Legende: „**Grau = gemessen, aber
  für diese Linse nicht gewichtet.**"
- **Confidence-Labels** (A/B/C) an jeder Achse und Kachel.
- **Archiv-Banner-Logik**: Validitäts-Banner bei Crawl-Problemen (Website-Achsen
  „not measured" statt 0, nur AVI bleibt gültig); archivierte Reports bleiben
  sichtbar als Archiv markiert und werden nicht als aktuelles Beispiel verlinkt.

Sprache und Klarheit des Outputs sind hier separat optimierbar — der Report ist
das Schaufenster des gesamten Audits.

## Code (Rendering, kein Prompt)

`~/audit-app/ai-visibility-audit/src/report_v2.py` — Funktionen `render_report`
und `save_report`.

WICHTIG — **kein LLM-Prompt**: Der Report ist reines HTML-Rendering. Das
eigentliche Narrativ (Maßnahmen-Texte, Begründungen) entsteht upstream in
`av-gap-strategist` (`measures.py`) und `av-website-scorer`. Diese Phase setzt
nur zusammen und stellt dar.

Es gibt **KEINE** `av-report-narrator.active.txt` — da kein Prompt existiert,
gibt es auch keine aktive Prompt-Variante.

## Eval-Signal (completeness)

Wert in `[0..1]`:

- **completeness = 1.0**, wenn ein Report gespeichert wurde UND mindestens eine
  Maßnahme enthalten ist.
- **completeness = 0.0** sonst.

Einfacher Vollständigkeits-Check: Ein leerer oder maßnahmenloser Report ist
nutzlos. Berechnet in `src/skill_signals.py`, geloggt nach `skill-runs.jsonl`
und in die DB.

## Optimierung (nur Vorschlag)

Da kein LLM-Prompt existiert, wird diese Phase von `av-eval-calibrator`
**bewertet, nicht automatisch mutiert**. Verbesserungen der Darstellung oder
Sprache (z.B. Executive Summary, bessere Visualisierungen via
`infographic-craft` / `d3-infografik`) sind **Code-/Template-Änderungen** und
gehen daher als **Change-Board-Vorschlag** ein — kein Auto-Apply.

## Design (Holocron)

Holocron-Palette:

- Deep Space `#0a0e17`
- Ochre-Amber `#E89A2A`
- Gold `#f4c869`

Reports werden unter `~/audit-app/ai-visibility-audit/reports/` gespeichert und
auf `audit.phibel.app` via `/reports/` ausgeliefert.

## Rubrik

- Klare Hierarchie: **Ergebnis-Kacheln → Linsen/Radar → Maßnahmen → Wette/Hypothese**.
- Maßnahmen mit **Aufwand + Quick-Win-Score** sichtbar.
- Quellen und Begründungen nachvollziehbar.
- Deutscher Markt → **deutsche Sprache**.
- Kein Fachjargon ohne Erklärung.
- Für Visuals die Skills `infographic-craft` / `d3-infografik` nutzen.

## Verwandte Skills

- **Upstream (Narrativ-Quelle):** `av-gap-strategist` (`measures.py`),
  `av-website-scorer`.
- **Visuals:** `infographic-craft`, `d3-infografik`.
- **Bewerter:** `av-eval-calibrator`.

done

Stand: 2026-07-10 (Feedback-Rework v2.1)