Aggressive Analytik ist mehr als Text-zu-SQL: Erkenntnisse aus Anthropic

Analytics-Schrott ist der neue AI-Schrott

Ein Beitrag von Anthropic vom 3. Juni 2026 zu Self-Service-Analytics sagt öffentlich das aus, was viele Datenteams auf die harte Tour gelernt haben: Agierende Analytics-Lösungen sind nicht dasselbe wie das Hinweisen von Claude Code auf eine Datenbank und das Stellen von Fragen dazu.

Die meisten kennen den Begriff AI-Schrott. Analytics-Schrott ist sein „Cousin“. Mit einem Programmieragenten kann jetzt jeder eine Datenbank anschließen und analytische Berichte erstellen. Das ist großartig, um die Einstiegshürden zu senken – doch andererseits überprüft fast niemand die Zahlen. Dashboards kommen als .html-Dateien, Confluence-Seiten oder Terminal-Screenshots, und nur wenige davon wurden überprüft. Der Grund ist ein falsches Sicherheitsgefühl: Da große Sprachmodelle Englisch so gut in SQL übersetzen, müssen die Antworten richtig sein – zumindest ist das die Annahme.

Diese Zuversicht ist fehl am Platz. Wenn die agentbasierte Analytik auf die Erstellung von Abfragen reduziert wird, wird das Problem zu eng gefasst und die zugrundeliegende Infrastruktur bleibt unberücksichtigt – obwohl sie darüber entscheidet, ob eine bestimmte Antwort hilft oder schadet. Anthropics eigener Entwurf stellt die Datenbasis, die Quellen der Wahrheit, die Fähigkeiten sowie die Validierung bereits vor dem Zeitpunkt ein, an dem Claude eine Abfrage sieht. Der Artikel listet klassische Praktiken der Datenverarbeitung als strenge Anforderungen auf und gibt Ratschläge, damit andere Teams die gleichen Fehler vermeiden können.

Der Artikel ist ein Beitrag über Enterprise AI, kein Forschungspapier, doch er gehört zu den klarsten Darstellungen im Produktumfeld darüber, was für vertrauenswürdige agierende Analysen erforderlich ist. Im Folgenden werden die wichtigsten Ideen nacheinander erläutert: Warum text-to-SQL das falsche Konzept ist, woher Unklarheiten entstehen, was Anthropic entwickelt hat, was vor dem Schreiben einer Abfrage vorhanden sein muss, die Rolle der semantischen Schicht sowie von Fähigkeiten, warum Bewertungen und Wartung wichtig sind – und wo ein Team anfangen könnte.

Warum text-to-SQL so viel Aufmerksamkeit erhält

Die Abfragenbildung ist der Teil, den man bereits in dreißig Sekunden demonstrieren kann. Man stellt eine Frage auf einfachem Englisch, beobachtet, wie das Modell eine Abfrage erstellt, diese gegen die Datenbank ausführt und anschließend eine Zahl oder einen Diagramm zurückgibt. Das wirkt magisch – besonders für Nicht-Techniker, die früher auf ein Analyseteam oder vorgefertigte Dashboards angewiesen waren.

Eine klare Erklärung sowie eine ordentliche Zahl von Claude oder Codex sagen nichts darüber aus, ob die Frage richtig beantwortet wurde. Nach Ansicht von Anthropic kann es dazu führen, dass Claude bei der Bearbeitung einer Aufgabe ein falsches Gefühl von Präzision vermittelt – und das ist die Falle.

Nehmen wir an, ein Interessent fragt: „Wie hoch waren die Umsätze aktiver Kunden im letzten Monat?“ Schon hier beginnen die analytischen Nuancen:

• Was macht einen Kunden zu einem aktiven?
• Welche Definition von Kunde gilt offiziell?
• Sind es Bruttoumsätze oder Nettoumsätze?
• Welches Datumsfeld ist relevant?
• Welche Rückerstattungen, Betrugsfilter oder Produktausschlüsse sollten berücksichtigt werden?

Text-zu-SQL kommt erst nachdem diese Entscheidungen getroffen wurden. Ein zuverlässiger Analyseagent benötigt daher eine umfassende Infrastruktur, die sein Verständnis des Geschäfts lenkt.

Dies spiegelt eine bekannte Google-Studie über versteckte technische Schulden in Machine-Learning-Systemen wider, die zeigte, dass das Modell eine winzige Box innerhalb des weitaus größeren Apparats der produktiven ML-Systeme ist.

Die obige Abbildung ist ein Screenshot aus dieser Studie. Dasselbe Bild gilt auch für Analyseagenten, wenn die kleine schwarze Box durch Text-zu-SQL ersetzt wird.

Anthropics Antwort stimmt mit dieser Sichtweise überein, wie in dem Satz „Daten sind kein Software.“ zu erkennen ist. Die Arbeit mit Analysedaten unterscheidet sich von der Entwicklung von Softwarefunktionen. In der Regel gibt es eine richtige Antwort aus einer richtigen Quelle, doch es gibt keine deterministische Möglichkeit, dies allein anhand des Endausgangs zu überprüfen. Zudem kann ein System fehlerfreien SQL-Code erstellen, ohne die geschäftliche Bedeutung überhaupt zu verstehen.

Anthropic liefert außerdem eine Reihe von Beispielen, die die beiden Paradigmen gegenüberstellen, wie in der untenstehenden Tabelle dargestellt.

Anthropic ordnet die entstehenden Fehler in drei Kategorien ein:

1. Ambiguität des Konzepts oder der Entität. Ein Benutzer verwendet Begriffe wie „aktive Nutzer“, „Umsatz“ oder „Retention“, und der Agent muss aus mehreren möglichen Interpretationen wählen. Die Unterschiede sind oft so subtil, dass eine falsche Antwort dennoch professionell erscheint.
2. Veraltete Daten. Dokumentationen, Tabellen und Geschäftsregeln ändern sich ständig. Eine Kennzahl, die vor drei Wochen noch korrekt war, kann plötzlich fehlerhaft werden, sobald sich das Schema ändert, eine neue Ausschlussregel eingeführt wird oder ein Dashboard neu erstellt wird.
3. Fehler bei der Suche. Irgendwo im System existiert die richtige Antwort, doch es gibt zu viele Suchmöglichkeiten. Das Modell überseht die richtige Tabelle, Kennzahl oder Dokument und basiert stattdessen zuversichtlich auf etwas Ähnlichem, das jedoch falsch ist.

Das Lager selbst kann nichts davon lösen. Es speichert Daten – nicht die vollständige Bedeutung des Geschäfts, die sich auf Metrikdefinitionen, semantische Modelle, Einschränkungen, Teamkonventionen, Verantwortlichkeiten und Historie verteilt. Im Umsatzbeispiel ist es einfach, einen GROUP BY-Befehl zu schreiben. Doch zu entscheiden, was „aktiv“ bedeutet, ist schwierig: Ein Kauf innerhalb von dreißig Tagen, bezahlte, nicht-betrügerische Nutzung in einem Abrechnungszeitraum oder ein domain-spezifischer Schwellenwert, der nur in der semantischen Schicht existiert.

Daher ist die Frage, ob Claude SQL schreiben kann, kaum von Interesse – schließlich schreibt er es vermutlich besser als die meisten Menschen. Die wichtige Frage ist, was Anthropic um Claude herum entwickeln musste, damit diese Probleme nicht länger die Ergebnisse dominieren.

Was Anthropic entwickelt hat

Die Antwort ist eine Kombination aus bewährten ingenieurtechnischen Praktiken und zusätzlichen Schichten, die von Agenten ermöglicht werden. Im Grunde handelt es sich um ein vollständiges System, bei dem Claude als Oberfläche dient und alles Weitere darunter liegt. Der Artikel gliedert es in vier Teile:

1. Datengrundlagen, also kanonische Datensätze, Datenmodelle, Transformationen, Tests, Frischheitsprüfungen und Metadaten.
2. Quellen der Wahrheit, die die semantische Schicht, die Herkunftslinien, den Geschäftskontext sowie sorgfältig ausgewählte Referenzmaterialien umfassen, die dabei helfen, eine Frage auf ein definiertes Bedeutungssystem zu übertragen.
3. Fähigkeiten, also Domänenprozeduren, die dem Modell zeigen, wie es arbeiten soll – und nicht nur, welche Daten vorhanden sind.
4. Validierung, einschließlich Offline-Bewertungen, Online-Prüfungen sowie Verfahren zur Nachverfolgung der Herkunft und zum Wartungszyklus.

Das obige Screenshot stammt aus dem Beitrag von Anthropic. Schauen Sie sich an, wo SQL in der Abfolge steht: nach all den schwierigen Entscheidungen. Wenn das Modell schließlich eine Abfrage erstellt, hat der Prozess bereits eingegrenzt, was die Frage bedeutet und welcher zugrunde liegende Weg Vertrauen verdient.

Diese Struktur erklärt die in der Schlagzeile genannte Zahl besser als die Wahl des Modells. Ein schneller Lesefluss lässt die 95-Prozent-Zahl wie einen Modell-Referenzwert erscheinen, während ein genauerer Blick zeigt, dass es sich um einen Systems-Referenzwert handelt – angesichts dessen, wie viel im Beitrag über die um Claude gewickelte Infrastruktur beschrieben wird und wie wenig über Claude selbst.

Was muss vor der Erstellung jeglicher SQL-Abfragen vorhanden sein

Anthropic betont ausdrücklich, dass die üblichen Methoden der Datenverarbeitung weiterhin gelten: dimensionales Modellieren, Überprüfungen auf Aktualität und Vollständigkeit, für den Einsatz bereite kanonische Datensätze sowie klare Datenwörterbücher. Nichts davon verschwindet nur weil die Schnittstelle konversationell geworden ist. Im Gegenteil: Die Bedeutung steigt, da der Nutzer nun ein Agent ist, der auf eine menschliche Frage reagiert. Ein Analyst kann manchmal erkennen, dass eine Tabelle nicht in Ordnung ist, während ein Agent falsche Annahmen weitaus schneller vergrößern kann.

Es gibt eine gewisse Ironie darin, dass ein Pionierunternehmen der Welt mitteilt, dass die gute alte Datenverarbeitung für Agenten unerlässlich ist. Keine dieser Praktiken ist neu – bereits jedes zwanzig Jahre alte Buch zum Thema Data Warehousing gibt denselben Rat. Dennoch lohnt es sich, sie erneut zu erwähnen.

Kanonische Datensätze

Eine kleine Anzahl streng regulierter logischer Modelle, von denen jedes die einzige Quelle der Wahrheit darstellt, verringert bereits vor dem eigentlichen Abruf die Anzahl der plausiblen Antworten. Möglicherweise sind unterschiedliche Aggregationsstufen erforderlich, doch die Zusammenfassungen sollten stets aus dieser kleinen Basis abgerufen werden. Dasselbe gilt für analytische Agenten: Wenn sie nur auf wenige vertrauenswürdige Datensätze zugreifen können und wissen, wie diese mit erweiterten Dimensionen verknüpft sind, sinkt die Wahrscheinlichkeit, die falsche Quelle auszuwählen, erheblich.

Metadaten als Produkt erster Klasse

Metadaten liefern dem Agenten eine funktionierende Beschreibung von Tabellen, Spalten, Granularitätsebenen, Eigentümern sowie Einschränkungen. Wenn niemand das Modell, die Bedeutung jeder Spalte sowie die Verknüpfungsmechanismen dokumentiert, füllt das große Sprachmodell alle Lücken mit Schätzungen.

Modelle, Dokumente, Dashboards und Skill-Dateien zusammenhalten

Colocation könnte einfach ein großes Monorepo bedeuten, doch Anthropic beschreibt etwas Präziseres. Fast alle Daten- und Codeelemente – von der Modellierung und der semantischen Schicht über Referenzdokumente bis hin zu kanonischen Dashboard-Definitionen – befinden sich in einem einzigen Repository, das durch CI-Prüfungen auf die Integrität zwischen den Schichten geschützt wird. Jede Änderung an der Modellierung, die ein nachgelagertes Dashboard beeinträchtigt oder eine dokumentierte Metrik ungültig macht, wird vom CI erkannt, und die Korrektur wird im selben Pull Request eingereicht.

Dies widerlegt die falsche Annahme, dass KI-Analysen die Bedeutung des Datenmanagements verringern. Je mehr Fragen über Modelle abgewickelt werden, desto deutlicher wird die Qualität der Modellierschicht sichtbar.

Auch andere Anbieter zeigen dies. Die dbt Semantic Layer existiert, damit Metrikdefinitionen nur einmal geschrieben werden und von jedem Tool wiederverwendet werden können. Microsoft empfiehlt, Power BI-Daten für Copilot mit auf KI vorbereiteten Schemata, überprüften Antworten und klaren Anweisungen zu gestalten, damit das Modell aus einem fundierten Kontext antworten kann. Snowflake entwickelt Cortex Analyst auf der Grundlage semantischer Modelle und überprüfter Abfragen, wobei die SQL-Generierung überwacht wird. Jedes Produkt lehrt dasselbe: Ein im Voraus vorbereiteter Kontext ist Teil der Antwort.

Die semantische Schicht ist die Karte des Agenten

Eine semantische Schicht ist eine architektonische Brücke, die rohe, komplexe Daten in vertraute Geschäftsbegriffe, Metriken und Beziehungen umwandelt. Sie befindet sich zwischen Datenspeichern wie Snowflake, Databricks oder BigQuery sowie Verarbeitungstools wie Power BI, Tableau oder KI-Agenten. Mit einer solchen Schicht kann man herausfinden, was eine Spalte bedeutet, welche Art eine andere hat, wie eine Metrik berechnet wird und wie Hierarchien sowie Tabellenzusammenhänge funktionieren.

Das obige Diagramm zeigt, wo diese Schicht liegt. Anthropic betrachtet sie als so zentral, dass ihre Agenten strukturell gezwungen sind, zunächst die semantische Schicht zu konsultieren. Das Funktionsprinzip besteht darin, dass das Modell von geregelter Bedeutung ausgeht und nicht von einer offenen Erforschung roher Tabellen. Anthropic geht noch einen Schritt weiter und bezeichnet es als schlechte Praxis, den Agenten zu erlauben, die semantische Schicht selbst zu erfinden. Menschen bleiben entscheidend dafür, sie in Ordnung zu halten – und das stammt aus einem der führenden Forschungslabore der Welt.

Die Branche neigt dazu, dieselbe Sichtweise einzunehmen. Snowflakes Cortex Analyst verwendet ein semantisches Modell, um Geschäftsfragen mit der Datenbankstruktur zu verknüpfen. Genie von Databricks lässt Domain-Experten Datensätze, Anweisungen, Beispiele für SQL sowie den Geschäftskontext bereitstellen. dbt speichert die Metriklogik an einem Ort, sodass nachgeschaltete Tools sie nicht erneut erstellen müssen, und Microsoft bringt überprüfte Antworten sowie KI-Anweisungen in das BI-Modell ein. Googles Data Science Agent benötigte etwas Ähnliches – eine pseudo-semantische Schicht namens Analyzer –, bevor seine Ergebnisse erfolgreich waren.

Ohne diese Karte tippt der Agent nur. Mit ihr konzentriert sich das Modell aufs Schlussfolgern innerhalb eines begrenzten Rahmens und muss keinen von Grund auf erstellen.

Beispielabfragen ergänzen die Schicht

Anthropic gibt an, dass ein Abfragedatensatz – also historische SQL-Anfragen aus Dashboards, Notizbüchern und früheren Analysen – einen positiven Gesamteffekt haben kann. Es reicht nicht aus, diesen Datensatz in Rohform an den Agenten zu übergeben. Stattdessen wird der Datensatz in strukturierte Referenzdokumente pro Domain sowie wiederverwendbare Analysemuster umgewandelt, die in den entsprechenden Fähigkeiten gespeichert werden. Die Abfragedatenhistorie dient als Rohmaterial für die Auswahl und Bearbeitung, nicht als Quelle der Wahrheit, die der Agent direkt liest.

Das hat auch praktische Folgen für die Frage, wer was besitzt. Da der Analyseagent auf geregelten Definitionen beruht, werden die Personen, die diese Definitionen pflegen – in der Regel Analyseingenieure und Domainbesitzer – zu einem Bestandteil der Qualitätskontrolle des Agents. Eine umstrittene Metrik ist dann nicht länger nur ein Streitpunkt im Dashboard, sondern ein Defekt in der gemeinsamen Schicht, der an einem einzigen Ort behoben wird und von jedem Nutzer, sei es menschlich oder durch ein Modell, erfasst wird. Teams, die bereits auf diese Weise arbeiten, werden den Umstieg auf Agents weniger schwierig finden als Teams, deren Metriklogik über verschiedene Notizbücher und BI-Tools verstreut ist.

Warum Fähigkeiten die Genauigkeit so stark beeinflussen

Eine semantische Schicht erklärt, was die Welt bedeutet, aber nicht, wie man in ihr handeln soll. Sie kann nicht angeben, welche Schritte ein guter Analyst unternimmt, wenn ein Interessengruppenmitglied eine mehrdeutige Frage stellt, die zwei mögliche Quellen sowie einen bekannten Randfall in einer bestimmten Region aufweist.

In Anthropics Analytiksystem funktionieren Skills wie codierte Anleitungen für Analysten und nicht wie Dokumentationen. Sie enthalten prozedurales Wissen:

• die Reihenfolge, in der Quellen überprüft werden
• der Punkt, an dem die semantische Schicht verwendet werden sollte und wo ein Ersatz möglich ist
• welche klärenden Fragen an die Beteiligten gestellt werden sollten
• die Einschränkungen, die in diesem Bereich gelten
• eine Methode, das Ergebnis vor dem Vertrauen darauf zu überprüfen
• die Herkunftsangaben, die in die endgültige Antwort einfließen

Anthropics stärkste Ergebnisse stammen von hier. Laut dem Abschnitt zu den Skills im Artikel erreichte Claude ohne diese nie mehr als 21 Prozent in ihren Analysebewertungen. Mit der Skill-Schicht stieg die Genauigkeit insgesamt auf über 95 Prozent und erreichte in einigen Bereichen etwa 99 Prozent.

Diese Zahl bestimmt, wie das System benannt werden sollte. Wenn der größte Fortschritt aus prozeduraler Anleitung und nicht aus einer besseren SQL-Generierung resultiert, handelt es sich im Grunde nicht um ein Text-zu-SQL-Produkt. Es ist vielmehr ein Analyse-Arbeitsfluss-Produkt mit integrierter Abfragenausführung.

Auch daran zu erinnern, was eine „Skill“ nicht ist, hilft. Es handelt sich weder um einen längeren Systemprompt noch um eine Ansammlung eingefügter Beispielabfragen. Es handelt sich um ein gepflegtes Artefakt mit Version, Auslösebedingung und definiertem Verfahren, das dann geladen wird, wenn die Frage dies erfordert. Dadurch lässt es sich in Pull-Requests überprüfen, gegen den Evaluationsdatensatz testen und leicht deaktivieren, wenn sich das zugrundeliegende Datenmodell ändert.

Das untenstehende Bild zeigt das Skill-Template, das Anthropic verwendet.

Zusammen bilden diese Artefakte eine vollständige Definition, und das Anhang wiederholt das gesamte Template.

Evaluierungen und Wartung sind genauso wichtig wie Prompts

Selbst ein gut aufgestellter Analyseagent verfällt im Laufe der Zeit. Sobald semantische Schichten, sorgfältig ausgewählte Beispiele und Fähigkeiten vorhanden sind, wird Abweichung zum nächsten Problem: Tabellen ändern sich, Definitionen verschieben sich, Dashboards werden neu erstellt und die Fähigkeiten passen nicht mehr zum ursprünglichen Modell. Ein Verfahren, das gestern noch richtig war, wird morgen zu veralteten Informationen.

Anthropic liefert ein eindrucksvolles Beispiel: Die Offline-Genauigkeit sank innerhalb eines Monats von etwa 95 Prozent auf etwa 65 Prozent, bevor Wartungsarbeiten als ingenieurtechnisches Problem betrachtet wurden. Diese Zahl macht die Wartung zu einer Zuverlässigkeitsanforderung statt zu einer bloßen Formalität.

Analytics weist hier eine praktische Eigenschaft auf: Die Bewertungen können auf den echten Werten beruhen, die jede korrekte Vorgehensweise erzeugen sollte. Sobald diese definiert sind, kann jeder andere Parameter des Systems daran ausgerichtet werden. Ein Team könnte die zweite Version einer Fähigkeit mit Haiku, Sonnet oder Opus auf verschiedenen Denkebenen testen, die Genauigkeit vergleichen und das Verhältnis von Kosten und Qualität auswählen – egal ob es darum geht, bei geringeren Kosten ausreichende Genauigkeit zu erreichen oder um jeden Preis die höchste Genauigkeit.

Ein ausgereiftes Analytics-System wird auf bestimmte Weise getestet: Es werden gespeicherte Fälle, explizite Aussagen sowie ein Feedbackschluss verwendet, der das Handbuch jedes Mal überarbeitet, wenn das System einen Fehler macht. Databricks verfolgt eine ähnliche Idee in seiner Genie-Dokumentation, indem es Response-Inspektionen, Benchmarks, vertrauenswürdige Ressourcen sowie sorgfältig ausgewählte Anleitungen in das Produkt integriert.

Hier spielen Prompte eine geringere Rolle, als die Leute oft annehmen. Qualität ist weiterhin wichtig, doch bei einer schwachen semantischen Struktur, veralteten Beispielen, schwankenden Fähigkeiten und ohne Bewertungen wird kein „heldenhafter“ Prompt das System auf Dauer retten. Aggressive Analytik funktioniert nur, wenn das umgebende System wie ein gepflegtes Produkt betrieben wird – nicht, wenn ein Modell unkontrollierten Zugriff erhält und selbst entscheiden muss, wie vorgegangen wird.

Wo ein Daten-Team anfangen könnte

Der beste Ausgangspunkt ist die einfachste Struktur, die funktionieren kann, wobei Komplexität schrittweise hinzugefügt wird – und zwar nur dort, wo die Ergebnisse zeigen, dass dies sinnvoll ist. Anthropics Anleitungen zur Erstellung effektiver Agenten vertreten denselben Standpunkt, und sein anschließender Artikel zur Analytik folgt diesem Prinzip. Hier sind fünf Schritte:

1. Wählen Sie ein bestimmtes Gebiet statt des gesamten Bereichs – beispielsweise die Qualität der Einnahmen, Support-Prozesse, Wachstumsstrategien oder Finanzberichterstattung. Wählen Sie einen Bereich mit einem klaren Verantwortlichen und wiederkehrenden Fragen.

Eine einzige, regulierte Quelle der Wahrheit etablieren. Anfragen können warten, bis das Domänengebiet kanonische Datensätze, schriftlich definierte Metriken, einen benannten Verantwortlichen sowie eine grundlegende Frischeüberwachung besitzt.

Den semantischen Layer an erste Stelle setzen und rohen SQL als Rückfallmöglichkeit beibehalten. Wenn eine Frage eindeutig auf die regulierten Bedeutungen abgebildet werden kann, sollte der Agent nicht direkt aus den Rohtabellen arbeiten.

Ein einfaches Skill- oder Playbook entwerfen, das zeigt, wie ein erfahrener Analyst in diesem Bereich vorgeht: Klärung, Auswahl der Quellen, Validierung, Berichterstattung sowie Angabe der Herkunft der Zahlen.

Vor einer breiten Einführung zunächst eine kleine Bewertungsmenge zusammenstellen. Zwanzig bis dreißig reale Fragen mit erwarteten Antworten und bekannten Randfällen lehren mehr als hundert interne Demonstrationen.

Etwas, was man vermeiden sollte, ist es, ein neuartiges Modell direkt in das System zu integrieren und dies als Strategie zu bezeichnen. Dieser Ansatz bringt kaum etwas außer der Erkenntnis, wie überzeugend eine falsche Antwort klingen kann.

Text-to-SQL nimmt als nützliche Ausführungsmethode einen Platz im Stack ein. Das Problem ist, dass es sich um ein zu begrenztes Konzept handelt, um das gesamte System zu beschreiben. Dieses Thema wird wahrscheinlich Teams in zwei Gruppen teilen: Menschen, die Text-to-SQL als eigenständiges Produkt betrachten, und Menschen, die darin nur eine schmale Schicht innerhalb eines umfassenderen Analyseworkflows sehen. Fragen, die gestellt werden sollten: Woher stammen die größten Fehler (Ambiguität, Abrufprobleme, Veraltetheit oder schwache Prozesse), existieren bereits die Grundlagen, die ein Analyseagent benötigt, oder würde das Projekt verborgene Probleme im Datenmodell aufdecken, und was umfasst der heutige Fähigkeitsbereich – ob Prompte, Runbooks, SQL-Beispiele oder Checklisten für Analysten.

Anhang: das vollständige Fähigkeitsmuster

Das vollständige Fähigkeitsmuster von Anthropic ist unten aufgeführt.

---
name: [warehouse-skill]
version: [x.y.z]
description: "IF the user asks to query [the company]'s data warehouse for any
  [list of business domains] question — THEN invoke this skill. DO NOT invoke
  for [adjacent engineering tasks] or questions with no data-warehouse component."
---

# [Warehouse] Skill Instructions

## Description
The single source of truth for safe and effective [warehouse] querying.
Referenced by other skills [listed] for query execution guidance.

Act as a Data Analyst, providing strategic insights and data-driven
recommendations but seek guidance along the way.

**Out-of-scope decisions**: [product areas, etc.] → surface data only,
state "decision is [owning team]'s call", do NOT take a position or author
code fixes.

## Executing queries
Priority:
1. **[Managed connection]** (if available): [query tool] / [schema tool]
2. **[CLI fallback]** (if installed): [default project, fallback project]
3. **Neither** — ask the user to authenticate, then stop

---

# Semantic Layer (REQUIRED first step)

The governed semantic layer is the **mandatory default path** for every data
question — same numbers as [the BI tool], joins/grain/filters baked in. Raw SQL
via the reference docs below is the **fallback**, used only after the
semantic-layer path is shown not to cover the ask.

## Required workflow
1. **Load** — [how to load the semantic layer in each runtime, with fallbacks]
2. **Discover** — search measures/dimensions by keyword; **always check
   segments** (the named canonical population filters — hand-rolled WHERE
   clauses for these are the dominant wrong-answer mode)
3. **Compile + run** — build the spec → compile to SQL → execute
4. **Fallback** — only if discovery finds no relevant metric or compile fails
   → raw SQL via `references/*.md` (PART 3 below)

> **Don't bail early.** Do NOT fall back to raw SQL on these grounds:
> - "[custom date filtering / cohorts]" → [covered by time-dimension specs]
> - "[needs a join]" → [the metric layer already encapsulates its joins]
> - [3–4 more pre-rebutted excuses agents use to skip the semantic layer]

### Date windows & timezone — decide before you query
- **As-of date vs trailing-N days**: [convention for each]
- **"Last week/month"** → the last *complete* calendar week/month, not trailing-7/30
- **Timezone default**: [TZ]; [exception for certain reporting rollups]
- **Freshness lag**: [some] tables settle late — anchor on MAX(date), not "yesterday"

---

# PART 1: MUST KNOW (Read First for Every Request)

## 🚀 Quick Start Workflow
1. **Check for red flags first**: [restricted/PII requests, gated domains,
   high-stakes asks that need extra validation]
2. **Out of scope — escalate, don't guess**: [access requests, pipeline
   troubleshooting, stale dashboards, root-cause assertions, product/pricing
   recommendations] → redirect to [the owning team], don't answer
3. **Clarify the request**: time period, segment, the business decision it informs
4. **Check for existing dashboards**: [per-domain dashboard catalogs]
5. **Identify the data source**: [navigation map below; prefer governed/aggregated tables]
6. **Execute the analysis**: [required filters + adversarial review]
7. **Deliver insights**: show methodology, differentiate observations from interpretations

## 🏢 Business Context

### Entity Disambiguation (MUST CLARIFY)
- **"[Term A]" can mean**: [entity 1] or [entity 2] — always clarify which
- **"[Term B]" can mean**: [entity 1] → [entity 2] → [entity 3] (one-to-many chain)
- **"Users"**: [which identifier gives accurate counts, and which ones inflate them]

### Business Terminology
- [Current product names vs deprecated aliases that still appear as frozen
  values in the data layer — write with the new names, filter with the old]
- [Key internal acronyms]
- **[Headline metric] calculations**: [monthly / default window / leading indicator]
- **Unfamiliar terms — search [internal docs], don't guess**

### Data Integrity Requirements ⚠️
- **NEVER**: make up data/columns; make speculative assertions beyond what data shows
- **ALWAYS**: use safe division; differentiate observations ("data shows X")
  from interpretations ("this suggests Y"); flag limitations

---

# PART 2: HOW TO DO (Follow During Execution)

## 🔧 Technical Execution Guide
- [Managed-connection tools and CLI invocation details]
- **PII protection**: for restricted data, return the SQL for the user to run
  themselves — do not return results

## 📊 Analysis Best Practices Guide
1. Clarify the ask before querying
2. Show your work (filters, inclusions/exclusions, freshness)
3. Clarify denominators
4. Consider sample bias
5. Connect to business impact
6. **Adversarial SQL review (MANDATORY)** — spawn the [sql-reviewer] sub-agent
   for every query before the final answer; blocking findings must be fixed
   and re-reviewed; do not self-certify
7. **Report with provenance** — every answer ends with a footer:
   > **Source:** [semantic layer | governed table | raw exploration] ·
   > **Confidence:** [tier] · **Reviewed:** [reviewer ✓, round N] ·
   > **Freshness:** [max date in the data] · **Owner:** [owning team]

---

# PART 3: DATA REFERENCES & RESOURCES

## 📚 Knowledge Base Navigation
### [Domain A] → `references/[domain_a].md`
- **Use for**: [kinds of questions]
- **Key tables**: [...]
- **Dashboards**: `references/[domain_a]_dashboards.json`

### [Domain B] → `references/[domain_b].md`
- **Use for**: [...]

[... one entry per business domain — a few dozen in total ...]

## ⚠️ Troubleshooting Guide

### When Information Is Missing
- [missing tables / access denied / outdated docs / unknown enum values → what to do]

### Field Naming Gotchas
- Use `[field_x_v2]` NOT `[field_x]`
- [Two similarly-named tables report the same metric at different grains — which to use]
- [Which of two plausible sources is canonical for the headline metric]
- [… a dozen more hard-won one-liners …]