L’analyse agente va au-delà du texte vers SQL : leçons tirées d’Anthropic

Les données d’analyse inutiles sont la nouvelle version des données AI inutiles

Un article publié le 3 juin 2026 par Anthropic sur les outils d’analyse en auto-service affirme ce que de nombreuses équipes de données ont appris à leurs dépens : l’analyse assistée par des agents n’est pas identique au fait de pointer Claude Code vers une base de données et de lui poser des questions.

La plupart des gens connaissent le terme « données AI inutiles ». Les données d’analyse inutiles en sont la version apparentée. Grâce à des agents de codage, n’importe qui peut désormais se connecter à une base de données et générer des rapports analytiques. C’est excellent pour abaisser les barrières à l’entrée, mais d’un autre côté, presque personne ne vérifie les chiffres. Les tableaux de bord apparaissent sous forme de fichiers .html, de pages Confluence ou d’captures d’écran de terminal, et très peu ont été vérifiés. La raison en est un faux sentiment de sécurité : comme les grands modèles linguistiques traduisent si bien l’anglais en SQL, on pense que les réponses doivent être correctes.

Ce sentiment de confiance est mal placé. Lorsque l’analytique agente se réduit à la génération de requêtes, le problème est abordé de manière trop étroite et l’infrastructure environnante reste ignorée, alors qu’elle détermine si une réponse donnée est utile ou préjudiciable. La propre conception d’Anthropic place les fondements de données, les sources de vérité, les compétences et la validation en amont du moment où Claude voit une requête. Cet article énumère des pratiques classiques d’ingénierie des données comme exigences impératives, et transmet des leçons permettant aux autres équipes d’éviter les mêmes erreurs.

Cet article fait partie de la série Enterprise AI et non d’un papier de recherche, mais c’est l’une des descriptions les plus claires en contexte pratique de ce qu’exigent les analyses agnitives fiables. Il présente successivement les idées principales : pourquoi l’approche text-to-SQL est inadaptée, d’où provient l’ambiguïté, ce que Anthropic a développé, ce qui doit exister avant d’écrire une requête, le rôle de la couche sémantique et des compétences, pourquoi les évaluations et la maintenance sont importantes, ainsi que par où une équipe pourrait commencer.

Pourquoi text-to-SQL attire autant d’attention

La génération de requêtes est la partie qui peut être démontrée en trente secondes. On pose une question en anglais simple, on observe le modèle écrire une requête, la lancer sur le système de stockage des données, et obtenir un chiffre ou un graphique en retour. Cela a l’air magique, surtout pour les personnes non techniques qui dépendaient auparavant d’une équipe d’analyse ou de tableaux de bord prédéfinis.

Une explication claire et un chiffre bien présenté fournis par Claude ou Codex ne disent rien sur le fait que la question ait été correctement répondue. Selon Anthropic, diriger Claude vers un entrepôt peut créer une fausse impression de précision, et c’est là le piège.

Prenons l’exemple d’un partie prenante qui demande : « Quel était le chiffre d’affaires des clients actifs le mois dernier ? » Les subtilités analytiques apparaissent immédiatement :

• Qu’est-ce qui fait d’un client un client actif ?
• Quelle est la définition officielle de client ?
• S’agit-il d’un chiffre d’affaires brut ou net ?
• Quel champ de date s’applique ?
• Quels remboursements, filtres de fraude ou exclusions de produits doivent être pris en compte ?

La génération de SQL à partir de texte n’intervient qu’après que ces décisions ont été prises. Un agent analytique fiable nécessite donc toute une infrastructure qui guide sa compréhension des activités commerciales.

Cela fait écho à un article bien connu de Google sur la dette technique cachée dans les systèmes d’apprentissage automatique, qui montrait que le modèle n’est qu’une petite boîte au sein de l’appareil bien plus vaste que représente la production d’algorithmes d’apprentissage automatique.

La figure ci-dessus est une capture d’écran de cet article. La même image s’applique aux agents d’analyse si la petite boîte noire est remplacée par un outil de conversion texte en SQL.

La réponse d’Anthropic correspond à cette approche, comme en témoigne la phrase « Les données ne sont pas du logiciel ». Le travail d’analyse échoue différemment des fonctionnalités logicielles : il existe généralement une seule réponse correcte provenant d’une seule source fiable, mais il n’existe pas de moyen déterministe pour la confirmer uniquement à partir du résultat final. De plus, un système peut générer du SQL impeccable tout en ignorant complètement sa signification métier.

Anthropic présente également un ensemble d’exemples mettant en contraste ces deux paradigmes, comme le montre le tableau ci-dessous.

Anthropic classe les échecs qui en résultent en trois catégories :

1. Ambiguïté du concept ou de l’entité. Un utilisateur mentionne des termes tels que « utilisateurs actifs », « chiffre d’affaires » ou « rétention », et l’agent doit choisir parmi plusieurs interprétations possibles. Les différences sont souvent suffisamment subtiles pour que une réponse erronée paraisse encore professionnelle.
2. Vieillissement des données. La documentation, les tableaux et les règles métier évoluent constamment. Une métrique qui était fiable il y a trois semaines peut devenir incorrecte sans que l’on s’en aperçoive, suite à un changement de schéma, à l’ajout d’une nouvelle règle d’exclusion ou à la refonte d’un tableau de bord.
3. Echec de la récupération. La bonne réponse existe quelque part dans le système, mais il y a trop d’éléments à explorer. Le modèle rate la table, la métrique ou le document appropriés et se base à tort sur quelque chose de similaire mais incorrect.

Le entrepôt à lui seul ne peut résoudre aucun de ces problèmes. Il stocke des données, mais pas le sens global de l’entreprise, qui se trouve dispersé dans des définitions de métriques, des modèles sémantiques, des mises en garde, des conventions d’équipe, des responsabilités et de l’historique. Dans l’exemple relatif aux revenus, écrire un GROUP BY est simple. Déterminer ce que signifie « actif » est difficile : une seule acquisition dans les trente jours, une utilisation non frauduleuse payée au cours d’une période de facturation, ou un seuil spécifique au domaine qui n’existe que dans la couche sémantique.

Ainsi, le fait que Claude puisse écrire du SQL n’est guère la question intéressante, car il le fait probablement mieux que la plupart des gens. La vraie question est ce qu’Anthropic a dû développer autour de Claude pour que ces problèmes cessent de dominer les résultats.

Ce qu’a développé Anthropic

La réponse est une combinaison de pratiques d’ingénierie éprouvées et de couches supplémentaires rendues possibles par les agents. En réalité, il s’agit d’un système complet où Claude agit comme interface en surface et tout le reste fonctionne en dessous. L’article le divise en quatre parties :

1. Les fondations de données, c’est-à-dire des ensembles de données canoniques, des modèles de données, des transformations, des tests, des vérifications de fraîcheur et des métadonnées.
2. Les sources de vérité, qui couvrent la couche sémantique, l’historique des données, le contexte métier ainsi que des matériaux de référence soigneusement sélectionnés pour aider à relier une question à un sens bien défini.
3. Les compétences, qui représentent des procédures sectorielles indiquant au modèle comment fonctionner et non seulement quels données existent.
4. La validation, incluant des évaluations hors ligne, des vérifications en ligne, ainsi que des boucles de provenance et de maintenance.

L’image d’écran ci-dessus provient de la publication d’Anthropic. Observez où se situe l’utilisation de SQL dans la séquence : après toutes les décisions difficiles. Lorsque le modèle écrit enfin une requête, l’ensemble des étapes antérieures a déjà réduit la portée de la question et déterminé quel chemin à suivre mérite confiance.

Cette structure explique mieux le chiffre cité en titre que le choix du modèle lui-même. Une lecture rapide fait paraître le chiffre de 95 % comme un indicateur relatif au modèle, tandis qu’une lecture attentive révèle qu’il s’agit d’un indicateur relatif au système, étant donné que la majeure partie du texte décrit les outils utilisés avec Claude et très peu de choses concernent directement Claude.

Qu’est-ce qui doit exister avant que toute requête SQL ne soit écrite ?

Anthropic précise que les méthodes classiques d’ingénierie des données restent applicables : modélisation dimensionnelle, vérifications de fraîcheur et d’exhaustivité, ensembles de données canoniques prêts à être utilisés, dictionnaires de données clairs. Rien de tout cela disparaît simplement parce que l’interface est devenue conversationnelle. Au contraire, les enjeux augmentent, puisque l’utilisateur est désormais un agent agissant en réponse à une question humaine. Un analyste peut parfois percevoir que quelque chose ne va pas dans une table, tandis qu’un agent peut amplifier rapidement une mauvaise hypothèse.

Il y a une pointe d’ironie dans le fait qu’une entreprise pionnière affirme au monde entier que l’ancienne ingénierie des données est essentielle pour les agents. Aucune de ces pratiques n’est nouvelle, et n’importe quel livre sur les entrepôts de données datant de vingt ans donne les mêmes conseils. Il reste utile de les rappeler.

Ensembles de données canoniques

Un petit ensemble de modèles logiques strictement réglementés, chacun étant la seule source de vérité, réduit le nombre de réponses plausibles avant même que la recherche ne commence. Divers niveaux d’agrégation peuvent être nécessaires, mais les synthèses doivent toujours être tirées de cette petite base. Il en va de même pour les agents analytiques : lorsqu’ils ne peuvent accéder qu’à quelques ensembles de données fiables et connaissent la manière dont ceux-ci se relient à des dimensions enrichies, les chances de choisir la mauvaise source diminuent fortement.

Les métadonnées en tant que produit de première classe

Les métadonnées fournissent à l’agent une description fonctionnelle des tables, des colonnes, du niveau de détail, des responsables et des réserves. Si personne ne documente le modèle, la signification de chaque colonne, ainsi que les clés de filiation ou de jointure, l’LLM comble chaque lacune par des suppositions.

Conserver les modèles, les documents, les tableaux de bord et les fichiers de compétences ensemble

La colocation pourrait simplement signifier un grand monorepo, mais Anthropic définit un concept plus précis. Presque tout le code lié aux données, allant de la modélisation et de la couche sémantique aux documents de référence et aux définitions des tableaux de bord canoniques, se trouve dans un seul répertoire protégé par des vérifications CI visant à assurer l’intégrité entre les différentes couches. Tout changement de modélisation susceptible de dégrader un tableau de bord ou de rendre invalide une métrique documentée est détecté par les CI, et la correction est intégrée dans la même demande de pull request.

Cela contredit l’idée reçue selon laquelle l’analyse par IA rendrait l’ingénierie des données moins importante. Plus de questions sont traitées par les modèles, plus la qualité de la couche de modélisation devient visible.

D’autres fournisseurs le présentent également. La couche sémantique dbt existe afin que les définitions de métriques soient écrites une seule fois et réutilisées par tous les outils. Microsoft conseille de préparer les données Power BI pour Copilot en utilisant des schémas prêts pour l’IA, des réponses vérifiées et des instructions explicites, afin que le modèle puisse répondre à partir d’un contexte solide. Snowflake développe Cortex Analyst autour de modèles sémantiques et de requêtes vérifiées, avec un suivi en temps réel de l’étape de génération SQL. Chaque produit enseigne la même chose : un contexte préparé à l’avance fait partie de la réponse.

La couche sémantique est la carte de l’agent

Une couche sémantique est un pont architectural qui transforme des données brutes et complexes en termes commerciaux, métriques et relations familiers. Elle se situe entre le stockage des données, comme Snowflake, Databricks ou BigQuery, et les outils de consommation, tels que Power BI, Tableau ou des agents d’IA. Avec une couche sémantique en place, on peut savoir ce que signifie une colonne, quel type possède une autre, comment est calculée une métrique, ainsi que le fonctionnement des hiérarchies et des relations entre tables.

Le diagramme ci-dessus montre l’emplacement de cette couche. Anthropic la considère comme si centrale que ses agents sont structurellement tenus de consulter d’abord la couche sémantique. Le principe de fonctionnement est que le modèle part d’un sens défini et non d’une exploration sans limite de tables brutes. Anthropic va même plus loin en qualifiant de mauvaise pratique le fait de laisser les agents inventer eux-mêmes la couche sémantique. Les humains restent essentiels pour en assurer la qualité, et cela provient de l’un des laboratoires de pointe mondiaux.

Le secteur tend vers la même vision. Cortex Analyst de Snowflake utilise un modèle sémantique pour relier les questions métier à la structure de la base de données. Genie de Databricks fait appel à des experts du domaine pour fournir des ensembles de données, des instructions, des exemples de SQL et un contexte métier. dbt centralise la logique des métriques afin que les outils ultérieurs n’aient pas à la recréer, tandis que Microsoft intègre des réponses vérifiées et des instructions d’IA dans le modèle BI. L’agent de science des données de Google avait besoin de quelque chose de similaire, une couche pseudo-sémantique nommée Analyzer, avant que ses résultats ne deviennent pertinents.

Sans cette carte, l’agent doit deviner. Avec elle, le modèle consacre ses efforts à raisonner dans un cadre défini plutôt qu’à en créer un de zéro.

Des requêtes d’exemple viennent enrichir cette couche

Anthropic indique qu’un corpus de requêtes, c’est-à-dire des SQL historiques provenant de tableaux de bord, de notebooks et d’analyses antérieures, peut avoir un effet net positif. Ce qui fonctionne, ce n’est pas de le fournir au agent sous forme brute. Au lieu de cela, le corpus est transformé en documents de référence structurés par domaine ainsi que en modèles d’analyse réutilisables intégrés dans les compétences de l’agent. L’historique des requêtes constitue une matière première pour la sélection des informations pertinentes, et non une source de vérité que l’agent lit directement.

Il existe également une conséquence pratique concernant le fait de savoir qui possède quoi. Comme l’agent d’analyse s’appuie sur des définitions réglementées, les personnes qui en assurent la maintenance, généralement des ingénieurs en analyse et les propriétaires du domaine, font partie intégrante de la garantie de qualité de l’agent. Une métrique contestée cesse d’être un sujet de désaccord lié à un tableau de bord pour devenir un défaut dans la couche partagée, un défaut qui est corrigé en un seul endroit et pris en compte par tous les utilisateurs, qu’ils soient humains ou des modèles. Les équipes qui travaillent déjà de cette manière trouveront le passage aux agents moins difficile que celles dont la logique des métriques est dispersée dans des fichiers de notes et des outils BI.

Pourquoi les compétences influencent autant la précision

Une couche sémantique explique ce que signifie le monde, mais pas comment y agir. Elle ne peut pas indiquer quelles étapes un bon analyste doit suivre lorsque un stakeholder pose une question ambiguë ayant deux sources possibles et un cas limite connu dans une seule région.

Dans le système d’analyse d’Anthropic, les compétences fonctionnent comme des guides d’analyse codés et non comme de la documentation. Elles contiennent des connaissances procédurales :

• l’ordre dans lequel les sources sont vérifiées
• le moment où il convient d’utiliser la couche sémantique et où un recours de secours est autorisé
• les questions à poser aux parties prenantes pour obtenir plus de précisions
• les réserves applicables dans ce domaine
• une manière de remettre en question le résultat avant de le croire
• les détails sur l’origine des informations intégrés dans la réponse finale

C’est là que réside le principal avantage d’Anthropic. Selon la section consacrée aux compétences dans l’article, Claude n’a jamais dépassé 21 % lors des évaluations d’analyse sans compétences. Avec l’utilisation de ces compétences, la précision a dépassé 95 % en moyenne et atteint environ 99 % dans certains domaines.

Ce chiffre change la manière dont le système devrait être nommé. Si la plus grande amélioration provient de directives procédurales et non d’une meilleure génération de SQL, alors il ne s’agit pas fondamentalement d’un produit texte vers SQL. Il s’agit plutôt d’un produit de flux de travail analytique incluant l’exécution de requêtes.

Il est également utile de se rappeler ce qu’une compétence n’est pas : ce n’est ni un prompt système plus long, ni une pile de requêtes d’exemple collées. C’est plutôt un artefact maintenu, doté d’une version, d’une condition déclencheuse et d’une procédure définie, chargé lorsque la question l’exige. Cela permet de le réviser dans une demande de pull request, de le tester à l’aide du jeu d’évaluation, et de le retirer facilement lorsque le modèle de données sous-jacent change.

L’image ci-dessous montre le modèle de compétence utilisé par Anthropic.

Tout cela ensemble constitue une définition complète, et l’annexe reproduit l’intégralité du modèle.

Les évaluations et la maintenance comptent autant que les prompts

Même un agent d’analyse bien conçu se dégrade avec le temps. Une fois que des couches sémantiques, des exemples sélectionnés et des compétences existent, le décalage devient le nouveau problème : les tableaux changent, les définitions évoluent, les tableaux de bord sont reconstruits et les compétences cessent de correspondre au modèle source. Une procédure qui était correcte hier devient un contexte obsolète le lendemain.

Anthropic donne un exemple frappant : l’exactitude hors ligne est passée d’environ 95 % à environ 65 % en l’espace d’un seul mois, avant que la maintenance des compétences ne soit considérée comme un problème d’ingénierie. Ce chiffre fait de la maintenance une exigence de fiabilité plutôt qu’une simple précaution.

L’analytique présente ici une propriété pratique : les évaluations peuvent se fonder sur des valeurs de référence que toute procédure correcte devrait reproduire. Une fois celles-ci définies, tous les autres paramètres du système peuvent être ajustés en fonction d’elles. Une équipe peut tester une deuxième version d’une compétence avec Haiku, Sonnet ou Opus à plusieurs niveaux de complexité, comparer la précision et choisir celle qui offre le meilleur équilibre entre coût et qualité, que ce soit une précision suffisante à moindre coût ou la plus haute précision quel que soit le prix.

Un système d’analytique mature est testé de manière spécifique : via des cas enregistrés, des affirmations explicites et un mécanisme de retour d’information qui réécrit les directives chaque fois que le système commet une erreur. Databricks propose une idée similaire dans sa documentation Genie, qui intègre l’inspection des réponses, des benchmarks, des ressources fiables et des instructions soigneusement sélectionnées au sein du produit.

Ici, les prompts comptent moins que ce à quoi on a tendance à penser. La qualité reste importante, mais en l’absence d’une couche sémantique solide, d’exemples à jour, de compétences stables et d’évaluations, aucun prompt magique ne permettra au système de tenir sur le long terme. L’analytique agente fonctionne lorsque le système environnant est géré comme un produit bien entretenu, et non lorsqu’un modèle dispose d’un accès direct et est laissé à son propre jugement pour improviser.

Où une équipe de données pourrait commencer

Le meilleur point de départ est la structure la plus simple qui puisse fonctionner, en ajoutant progressivement de la complexité uniquement là où les résultats montrent que cela en vaut la peine. Les conseils d’Anthropic sur la création d’agents efficaces avancent le même argument, et son article sur l’analytique suit cette logique. Voici cinq étapes :

1. Sélectionnez un domaine précis plutôt que l’ensemble du système, comme la qualité des revenus, les opérations de support, les canaux de croissance ou la comptabilité financière. Choisissez un domaine pour lequel il existe un responsable clair et des questions récurrentes.

Établir une source unique et contrôlée de vérité. Les requêtes peuvent attendre que le domaine dispose de jeux de données canoniques, de définitions de métriques écrites, d’un responsable désigné et d’un suivi de fraîcheur de base.

Placer la couche sémantique en premier et conserver le SQL brut comme solution de secours. Lorsqu’une question correspond clairement à une signification gérée, l’agent ne devrait pas utiliser directement les tables brutes.

Élaborer une seule compétence ou un guide succinct qui décrive comment un analyste compétent travaille dans ce domaine : clarifier, choisir les sources, valider, présenter des rapports et indiquer d’où proviennent les chiffres.

Créer un petit ensemble d’évaluation avant d’élargir l’application. Vingt à trente questions réelles, avec des réponses attendues et des cas limites connus, enseignent plus qu’une centaine de démonstrations internes.

Il faut éviter de relier directement un modèle de pointe au système de stockage en prétendant qu’il s’agit d’une stratégie. Cette approche ne permet d’apprendre que peu de choses, à part à quel point une réponse fausse peut sembler convaincante.

Text-to-SQL occupe une place dans la pile d’exécution en tant que méthode utile. Le problème, c’est qu’il s’agit d’un concept trop restreint pour décrire l’ensemble du système. Ce sujet risque de diviser les équipes en deux groupes : ceux qui considèrent Text-to-SQL comme un produit à part entière, et ceux qui y voient une simple couche au sein d’un flux de travail analytique plus large. Des questions pertinentes à se poser : d’où proviennent les échecs les plus fréquents (ambiguïté, récupération de données, obsolètes ou processus insuffisants) ? Les fondements nécessaires à un agent analytique existent-ils déjà, ou le projet révélera-t-il des dettes cachées dans le modèle de données ? Quel est l’ensemble des compétences actuellement disponibles, qu’il s’agisse de prompts, de guides d’exécution, d’exemples SQL ou de listes de contrôle pour les analystes ?

Appendice : le modèle complet de compétence

Le modèle complet de compétence fourni par Anthropic est présenté ci-dessous.

---
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 …]