---
name: av-mention-detector
description: Erkennt in jeder KI-Antwort Marken-/Wettbewerber-Nennungen und zitierte Quell-Domains und trennt Mention Rate ⟂ Share of Voice (SoV nur mit Peer-Set/Connected-Audit, solo = nur Mention Rate, nie erfunden) für die Phase-3-Auswertung des KI-Sichtbarkeits-Gap-Assessments (frueher ARD-Readiness-Audit).
---

> **EVN:** Dieser Skill misst die Eigenschaft (Stellhebel) **„AI Answer Presence"** → trägt zum Vorteil **Sichtbarkeit** bei → Nutzen **Auffindbarkeit**.

# av-mention-detector — Mention & Citation Detector (Phase 3)

## Zweck

Dieser Skill ist die **Auswertungs-Logik der Phase 3** im KI-Sichtbarkeits-Gap-Assessment. Für jede Antwort einer KI-Suchmaschine erkennt er:

- ob die **eigene Marke** genannt wird,
- ob und welche **Wettbewerber** genannt werden,
- welche **Domains** als Quelle zitiert wurden (und ob die eigene Domain darunter ist).

Daraus entstehen die Antwort-Metriken des Audits:

1. **Mention Rate** (= Visibility Rate) — in wie vielen Prompts taucht die Marke überhaupt auf.
2. **Share of Voice (SoV)** — Anteil eigener Nennungen/Empfehlungen **relativ zum Wettbewerbsfeld**.
3. **Zitierfähigkeit** — Citation Rate (in wie vielen Antworten wird die eigene Domain als Quelle zitiert).

Zusätzlich werden die **„Gaps"** ermittelt: Prompts, in denen die eigene Marke fehlt, aber Wettbewerber genannt werden — die wertvollsten Hebel für Verbesserungen.

## Mention Rate ⟂ Share of Voice (v3 — zwei getrennte Headline-Zahlen)

**Mention Rate** und **Share of Voice** sind im v3-Report **zwei sichtbar getrennte Kennzahlen**, nicht eine vermischte Größe:

- **Mention Rate** ist absolut messbar — auch ohne Wettbewerber (eine Domain genügt).
- **Share of Voice** ist **relativ** und braucht ein **Vergleichsfeld**: SoV = eigene Nennungen/Empfehlungen ÷ (eigene + Wettbewerber-Nennungen).

**Cold-Solo-Guardrail (Decision #3):** Im **Cold Solo-Audit** (eine Domain, kein Peer-Set) wird **NUR die Mention Rate** ausgegeben; **SoV bleibt `None`** und wird im Report als „Vergleichsfeld nötig → Gruppen-/Connected-Audit" markiert — **niemals erfinden**. SoV wird nur berechnet/gezeigt, wenn ein echtes Peer-Set vorliegt (**Gruppen-Audit**) oder First-Party-Daten (**Paid/Connected**).

## Wann nutzen

- Wenn ein Audit-Lauf die KI-Antworten ausgewertet braucht (Phase 3).
- Wenn Visibility Rate, Share of Voice, Citation Rate oder die Gap-Liste berechnet werden sollen.

## Code (Logik, kein Prompt)

`~/audit-app/ai-visibility-audit/src/audit.py`:

- **`_mentions`** — case-insensitive, regex-escaped Suche nach einem Namen im Antworttext.
- **`_analyze`** — markiert pro Antwort `brand_mentioned`, `competitors_mentioned`, `own_domain_cited` und sammelt `cited_domains`.
- **`compute_metrics`** — aggregiert über alle Prompts zu Visibility / Share of Voice / Citation Rate / Gaps.

**WICHTIG — LOGIK-SKILL, KEIN LLM-PROMPT.** Dieser Skill kapselt **Erkennungs-LOGIK (Regex)**, kein optimierbares Prompt-Artefakt. Es gibt deshalb **keine `av-mention-detector.active.txt`**. Das README des Tools nennt die naive Wortgrenzen-Zählung ausdrücklich als Schwachstelle: Synonyme, Schreibvarianten und Entity-Mehrdeutigkeit werden heute nicht erkannt.

## Eval-Signal (Drift-Wächter)

- **Signal:** `consistency` (0..1) — Übereinstimmung des Produktiv-Detektors mit einem **strikten Wortgrenzen-Recheck** `(?<!\w)name(?!\w)` über alle Marken- und Wettbewerber-Checks.
- **Funktion:** Es ist ein **DRIFT-WÄCHTER**. Fällt die Konsistenz, deutet das auf Erkennungsprobleme hin — typischerweise **Teilstring-Treffer** (ein kurzer Markenname steckt in einem anderen Wort).
- **Berechnung:** in `src/skill_signals.py`, geloggt nach `skill-runs.jsonl` und in die DB.

## Optimierung (nur Vorschlag, kein Auto-Apply)

Da **kein LLM-Prompt** existiert, wird dieser Skill von **`av-eval-calibrator` BEWERTET, aber NICHT automatisch mutiert**.

Verbesserungen — etwa entity-aware / fuzzy / synonym-tolerante Erkennung oder ein LLM-gestützter Detektor — sind **Code-Änderungen**. Sie gehen als **Change-Board-Vorschlag an Frank** und werden **niemals automatisch übernommen** (kein Auto-Apply).

## Bekannte Schwächen (Rubrik)

- **Teilstring-Fehltreffer:** kurze Markennamen, die als Teil anderer Wörter auftauchen, werden fälschlich als Nennung gezählt.
- **Nicht erkannte Synonyme/Abkürzungen:** alternative Schreibweisen, Kurzformen und Markenvarianten werden übersehen.
- **Domain-Heuristik bei Citations:** taucht ein Wettbewerbername als Domain-Bestandteil auf, kann die Zitat-Zählung unter- oder überzählen.

**Ziel-Verbesserung:** entity-bewusste, synonym-tolerante, fuzzy Erkennung.

## Verwandte Skills

- **Upstream:** `av-search-framing` — liefert die KI-Antworten, die hier ausgewertet werden.
- **Optimierer/Bewerter:** `av-eval-calibrator` — bewertet das Drift-Signal und erzeugt (nur als Vorschlag) Verbesserungen.

done

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