Inicio / Artículos

El análisis agente es más que texto a SQL: lecciones de Anthropic

Qué dice el artículo de análisis de autoservicio de Anthropic sobre las capas semánticas, las habilidades, las evaluaciones y los fundamentos de datos, y por qué el texto a SQL por sí solo genera una falsa sensación de precisión.

Editor: REACTAPP.TOP17 min de lectura3990 palabras

Fuentes: Anthropic is telling you that Agentic Analytics is not just text-to-SQL

La basura analítica es la nueva basura de la IA

Un artículo publicado por Anthropic el 3 de junio de 2026 sobre análisis de autoservicio expresa en público lo que muchos equipos de datos han aprendido a costa propia: el análisis basado en agentes no es lo mismo que dirigir Claude Code a una base de datos y hacerle preguntas.

La mayoría de las personas conoce el término “basura de la IA”. La basura analítica es su pariente. Con un agente de programación, ahora cualquiera puede conectarse a una base de datos y generar informes analíticos. Eso es excelente para reducir la barrera de entrada, pero por otro lado, casi nadie verifica las cifras. Los paneles de control llegan en forma de archivos .html, páginas de Confluence o capturas de pantalla de la terminal, y pocos de ellos han sido verificados. La razón es una falsa sensación de seguridad. Dado que los LLM traducen tan bien del inglés al SQL, se cree que las respuestas deben ser correctas.

Esa confianza está mal planteada. Cuando el análisis basado en agentes se reduce a la generación de consultas, el problema se aborda de manera demasiado limitada y la infraestructura circundante pasa desapercibida, aun cuando es ella quien determina si una respuesta concreta ayuda o perjudica. El propio diseño de Anthropic coloca las bases de datos, las fuentes de verdad, las habilidades y la validación antes incluso de que Claude vea una consulta. El artículo enumera prácticas clásicas de ingeniería de datos como requisitos indispensables, y transmite lecciones para que otros equipos puedan evitar los mismos errores.

El artículo es una publicación de Enterprise AI, no un trabajo de investigación, pero constituye uno de los resúmenes más claros sobre los requisitos para contar con análisis agentes fiables. A continuación, se exponen sus ideas principales en orden: por qué el enfoque text-to-SQL es inadecuado, de dónde proviene la ambigüedad, qué desarrolló Anthropic, qué debe existir antes de redactar una consulta, el papel de la capa semántica y las habilidades, por qué son importantes las evaluaciones y el mantenimiento, y dónde podría comenzar un equipo.

Por qué el enfoque text-to-SQL recibe tanta atención

La generación de consultas es la parte que se puede demostrar en treinta segundos. Se plantea una pregunta en inglés sencillo, se observa cómo el modelo escribe la consulta, se ejecuta contra el almacén de datos y se obtiene un número o un gráfico. Parece mágico, especialmente para personas no técnicas que antes dependían de un equipo de análisis o de paneles ya preparados.

Una explicación clara y un número ordenado proporcionados por Claude o Codex no indican en absoluto si la pregunta fue respondida correctamente. Según Anthropic, dirigir a Claude hacia un almacén puede generar una falsa sensación de precisión, y esa es la trampa.

Tomemos como ejemplo a un stakeholder que pregunta: “¿Cuál fue el ingreso de clientes activos el mes pasado?”. Las sutilezas analíticas comienzan de inmediato:

  • ¿Qué hace que un cliente sea activo?
  • ¿Cuál es la definición oficial de cliente?
  • ¿Se trata de ingresos brutos o netos?
  • ¿Qué campo de fecha se aplica?
  • ¿Qué reembolsos, filtros contra fraudes o exclusiones de productos deben aplicarse?

La conversión de texto a SQL solo se realiza después de tomar esas decisiones. Por lo tanto, un agente analítico fiable necesita toda una infraestructura que guíe su comprensión del negocio.

Esto hace eco de un conocido artículo de Google sobre la deuda técnica oculta en los sistemas de aprendizaje automático, que demostró que el modelo es una pequeña caja dentro del aparato mucho más grande del ML en producción.

La figura anterior es la captura de pantalla de ese artículo. La misma imagen se aplica a los agentes analíticos si la pequeña caja negra se reemplaza por text-to-SQL.

La respuesta de Anthropic coincide con ese enfoque, como se ve en la frase “Los datos no son software”. El trabajo analítico falla de manera diferente a las funciones de software. Por lo general, existe una respuesta correcta proveniente de una fuente correcta, pero no hay forma determinista de confirmarla únicamente a partir del resultado final. Además, un sistema puede generar SQL impecable mientras ignora por completo el significado empresarial.

Anthropic también proporciona un conjunto de ejemplos que contrastan estos dos paradigmas, como se muestra en la tabla a continuación.

Anthropic clasifica los fallos resultantes en tres modos:

  1. Ambigüedad en el concepto o entidad. Un usuario menciona “usuarios activos”, “ingresos” o “retención”, y el agente debe elegir entre varias implementaciones posibles. Las diferencias suelen ser lo suficientemente sutiles como para que una respuesta incorrecta siga pareciendo profesional.
  2. Viejo de los datos. La documentación, las tablas y las reglas comerciales siguen cambiando. Una métrica que era correcta hace tres semanas puede fallar silenciosamente cuando cambia el esquema, se aplica una nueva regla de exclusión o se reconstruye un panel de control.
  3. Fallo en la recuperación. En algún punto del sistema existe la respuesta correcta, pero hay demasiada información para buscar. El modelo pasa por alto la tabla, métrica o documento adecuado y se basa con confianza en algo similar pero incorrecto.

El almacén por sí solo no puede resolver ninguno de estos problemas. Almacena datos y no el significado completo del negocio, que está distribuido en definiciones de métricas, modelos semánticos, advertencias, convenciones del equipo, responsabilidades e historial. En el ejemplo de ingresos, escribir un GROUP BY es sencillo. Decidir qué significa “activo” es difícil: una compra dentro de treinta días, un uso no fraudulento pagado en un período de facturación, o umbral específico del dominio que solo existe en la capa semántica.

Por lo tanto, si Claude puede escribir SQL apenas es la pregunta interesante, ya que probablemente lo haga mejor que la mayoría de las personas. La pregunta útil es qué tuvo que desarrollar Anthropic alrededor de Claude para que estos problemas dejaran de dominar los resultados.

Qué desarrolló Anthropic

La respuesta es una combinación de prácticas de ingeniería probadas y capas adicionales que los agentes hacen posibles. En efecto, se trata de un sistema completo en el que Claude funciona como interfaz en la parte superior y todo lo demás opera en su interior. La publicación lo organiza en cuatro partes:

  1. Fundamentos de datos, es decir, conjuntos de datos canónicos, modelos de datos, transformaciones, pruebas, verificaciones de actualidad y metadatos.
  2. Fuentes de verdad, que abarcan la capa semántica, el historial de los datos, el contexto empresarial y material de referencia seleccionado que ayuda a relacionar una pregunta con un significado establecido.
  3. Habilidades, que son procedimientos específicos de cada área que indican al modelo cómo actuar y no solo qué datos existen.
  4. Validación, que incluye evaluaciones offline, verificaciones en línea, trazabilidad y ciclos de mantenimiento.

La captura de pantalla anterior proviene del post de Anthropic. Fíjese en dónde aparece SQL en la secuencia: después de todas las decisiones difíciles. Cuando el modelo finalmente escribe una consulta, la estructura ya ha reducido el significado de la pregunta y determinado qué ruta seguir para confiar en ella.

Esta estructura explica mejor el número mencionado en el título que la elección del modelo. Una lectura rápida hace que la cifra del 95 por ciento suene como un punto de referencia del modelo, mientras que una lectura detallada revela que se trata de un punto de referencia del sistema, dada la cantidad de información en el post sobre los mecanismos utilizados con Claude y lo poco que se habla de Claude en sí.

Qué debe existir antes de escribir cualquier consulta SQL

Anthropic deja claro que la ingeniería de datos tradicional sigue siendo relevante: modelado dimensional, verificaciones de actualidad e integridad, conjuntos de datos canónicos listos para su uso y diccionarios de datos claros. Nada de esto desaparece solo porque la interfaz se ha vuelto conversacional. De hecho, las implicaciones son aún mayores, ya que el consumidor ahora es un agente que actúa en respuesta a una pregunta humana. Un analista a veces puede percibir que hay algo incorrecto en una tabla, mientras que un agente puede amplificar un error de suposición mucho más rápidamente.

Hay cierta ironía en que una empresa pionera le diga al mundo que la buena y antigua ingeniería de datos es esencial para los agentes. Ninguna de estas prácticas es nueva, y cualquier libro sobre almacenes de datos publicado hace veinte años da el mismo consejo. Aún así, vale la pena repetirlo.

Conjuntos de datos canónicos

Un conjunto reducido de modelos lógicos estrictamente regulados, cada uno como única fuente de verdad, disminuye la cantidad de respuestas plausibles incluso antes de comenzar la recuperación. Pueden ser necesarios diferentes niveles de agregación, pero los resúmenes siempre deben basarse en esa pequeña base. Lo mismo ocurre con los agentes analíticos: cuando solo pueden acceder a unos pocos conjuntos de datos confiables y saben cómo estos se relacionan con dimensiones enriquecidas, la probabilidad de elegir la fuente incorrecta disminuye drásticamente.

Metadatos como producto de primera categoría

Los metadatos proporcionan al agente una descripción funcional de las tablas, columnas, nivel de detalle, propietarios y limitaciones. Si nadie documenta el modelo, el significado de cada columna ni las claves de relación o herencia, el LLM llena todos los vacíos con conjeturas.

Mantener modelos, documentos, paneles de control y archivos de habilidades juntos

La colocación podría significar simplemente un gran monorepo, pero Anthropic define un concepto más preciso. Casi todo el código relacionado con los datos, desde el modelado y la capa semántica hasta las documentaciones de referencia y las definiciones de los paneles de control canónicos, se encuentra en un único repositorio protegido por verificaciones de CI que aseguran la integridad entre las diferentes capas. Cualquier cambio en el modelado que pueda dañar un panel de control posterior o invalidar una métrica documentada es detectado por CI, y las correcciones se incluyen en la misma solicitud de pull request.

Eso refuta la idea errónea de que el análisis con IA hace que la ingeniería de datos sea menos importante. Cuantas más preguntas pasen por los modelos, más visible se vuelve la calidad de la capa de modelado.

Otros proveedores también lo muestran. La capa semántica de dbt existe para que las definiciones de métricas se escriban una sola vez y sean reutilizadas por todas las herramientas. Microsoft recomienda preparar los datos de Power BI para Copilot con esquemas listos para la IA, respuestas verificadas e instrucciones explícitas, de modo que el modelo responda a partir de un contexto fundamentado. Snowflake desarrolla Cortex Analyst a partir de modelos semánticos y consultas verificadas, con monitoreo en la etapa de generación de SQL. Cada producto enseña lo mismo: el contexto preparado con antelación forma parte de la respuesta.

La capa semántica es el mapa del agente

Una capa semántica es un puente arquitectónico que convierte datos brutos y complejos en términos comerciales, métricas y relaciones familiares. Se encuentra entre el almacenamiento de datos, como Snowflake, Databricks o BigQuery, y las herramientas de consumo, tales como Power BI, Tableau o agentes de IA. Con una capa semántica en su lugar, se puede responder a qué significa una columna, qué tipo tiene otra, cómo se calcula una métrica y cómo funcionan las jerarquías y las relaciones entre tablas.

El diagrama anterior ilustra dónde se encuentra esa capa. Anthropic la considera tan fundamental que sus agentes están estructuralmente obligados a consultar primero la capa semántica. El principio operativo es que el modelo parte de un significado definido y no de una exploración abierta de tablas sin estructura. Anthropic va aún más allá y considera mala práctica permitir que los agentes inventen por sí mismos la capa semántica. Los seres humanos siguen siendo esenciales para mantenerla en buen estado, y esto proviene de uno de los laboratorios de vanguardia del mundo.

La industria está adoptando la misma visión. Cortex Analyst de Snowflake utiliza un modelo semántico para vincular las preguntas empresariales con la estructura de la base de datos. Genie de Databricks cuenta con expertos en el área que proporcionan conjuntos de datos, instrucciones, ejemplos de SQL y contexto empresarial. dbt guarda la lógica de las métricas en un solo lugar para que las herramientas posteriores dejen de reconstruirla, mientras que Microsoft integra respuestas verificadas e instrucciones de IA en el modelo de BI. El agente de ciencia de datos de Google necesitaba algo similar, una capa pseudo-semántica llamada Analyzer, antes de que sus resultados pudieran destacarse.

Sin ese mapa, el agente solo puede adivinar. Con él, el modelo dedica sus esfuerzos a razonar dentro de un mundo definido y no tiene que crear uno desde cero.

Las consultas de ejemplo se añaden a la capa

Anthropic indica que un corpus de consultas, es decir, SQL histórico proveniente de paneles, cuadernos de notas y análisis anteriores, puede tener un efecto neto positivo. Lo que funciona no es alimentar al agente con este material en bruto. En su lugar, el corpus se transforma en documentos de referencia estructurados por dominio y patrones de análisis reutilizables capturados en habilidades específicas. El historial de consultas es material bruto para su curación, y no una fuente de verdad que el agente lea directamente.

También existe una consecuencia práctica en cuanto a quién posee qué. Dado que el agente de análisis se basa en definiciones reguladas, las personas que mantienen esas definiciones, generalmente ingenieros de análisis y propietarios del dominio, pasan a formar parte del proceso de garantía de calidad del agente. Una métrica controvertida deja de ser un motivo de discusión en el panel de control y se convierte en un defecto en la capa compartida, uno que se corrige en un único lugar y es detectado por todos los usuarios, ya sean humanos o modelos. Los equipos que ya trabajan de esta manera encontrarán que la transición a los agentes es menos dolorosa que aquellos cuya lógica de métricas está dispersa en cuadernos de notas y herramientas de BI.

Por qué las habilidades influyen tanto en la precisión

Una capa semántica explica qué significa el mundo, pero no cómo actuar en él. No puede indicar qué pasos sigue un buen analista cuando un interesado plantea una pregunta ambigua que tiene dos fuentes posibles y un caso límite conocido en una sola región.

En el sistema de análisis de Anthropic, las habilidades funcionan como guías de análisis codificadas y no como documentación. Contienen conocimiento procedural:

  • el orden en el que se verifican las fuentes
  • el punto en el que se debe utilizar la capa semántica y dónde se permite recurrir a una solución alternativa
  • qué preguntas de aclaración hacer a las partes interesadas
  • las consideraciones aplicables en ese dominio
  • una forma de cuestionar el resultado antes de confiar en él
  • los detalles de origen que se incluyen en la respuesta final

La mayor ventaja de Anthropic proviene de aquí. Según la sección dedicada a las habilidades del artículo, Claude nunca superó el 21 por ciento en sus evaluaciones de análisis sin utilizar habilidades. Con la capa de habilidades, la precisión aumentó por encima del 95 por ciento en promedio y alcanzó aproximadamente el 99 por ciento en algunos dominios.

Esa cifra cambia el nombre que debería tener el sistema. Si el mayor avance proviene de la guía procedural y no de una generación mejor de SQL, entonces esto no es fundamentalmente un producto de texto a SQL. Es un producto de flujo de trabajo analítico que incluye la ejecución de consultas.

También ayuda recordar qué no es una “skill”. No se trata de un prompt del sistema más extenso, ni de un montón de consultas de ejemplo pegadas. Es un artefacto mantenido con versión, condición de activación y procedimiento definido, que se carga cuando la pregunta lo requiere. Eso permite revisarlo en una solicitud de integración, probarlo con el conjunto de evaluación y retirarlo fácilmente cuando cambia el modelo de datos subyacente.

La imagen a continuación muestra el template de “skill” que utiliza Anthropic.

Juntos, estos artefactos constituyen una definición completa, y el apéndice reproduce todo el template.

Las evaluaciones y el mantenimiento son tan importantes como los prompts

Incluso un agente de análisis bien fundamentado se deteriora con el tiempo. Una vez que existen capas semánticas, ejemplos seleccionados y habilidades, el desvío se convierte en el siguiente problema: las tablas cambian, las definiciones se modifican, los paneles de control se reconstruyen y las habilidades dejan de coincidir con el modelo original. Un procedimiento que era correcto ayer se convierte en un contexto obsoleto al día siguiente.

Anthropic ofrece un ejemplo contundente: la precisión fuera de línea disminuyó de aproximadamente el 95 por ciento al 65 por ciento en un solo mes, antes de que el mantenimiento de las habilidades comenzara a considerarse un problema de ingeniería. Esa cifra convierte el mantenimiento en un requisito de fiabilidad en lugar de algo meramente opcional.

La analítica presenta aquí una ventaja importante: las evaluaciones pueden basarse en valores reales que cualquier procedimiento correcto debería reproducir. Una vez definidos estos valores, se puede ajustar todos los demás parámetros del sistema en función de ellos. Un equipo podría probar la segunda versión de una habilidad utilizando Haiku, Sonnet u Opus en varios niveles de complejidad, comparar la precisión y elegir la opción que mejor equilibre costo y calidad, ya sea una precisión suficiente a un costo menor o la máxima precisión a cualquier precio.

Un sistema de analítica maduro se prueba de una manera específica: mediante casos almacenados, afirmaciones explícitas y un bucle de retroalimentación que modifica las instrucciones cada vez que el sistema comete un error. Databricks tiene una idea similar en su documentación Genie, donde integra la inspección de respuestas, puntos de referencia, recursos confiables e instrucciones cuidadosamente seleccionadas en el producto.

Aquí los prompts importan menos de lo que la gente suele pensar. La calidad sigue siendo importante, pero con una capa semántica débil, ejemplos obsoletos, habilidades en declive y sin evaluaciones, ningún prompt “heroico” podrá salvar al sistema a largo plazo. El análisis basado en agentes funciona cuando el sistema circundante se gestiona como un producto bien mantenido, y no cuando un modelo tiene acceso directo y se le deja improvisar.

Dónde podría empezar un equipo de datos

El mejor punto de partida es la estructura más simple que pueda funcionar, añadiendo complejidad gradualmente y solo donde los resultados demuestren que vale la pena. La guía de Anthropic para crear agentes eficaces plantea el mismo argumento, y su artículo de análisis lo respalda. A continuación se presentan cinco pasos:

  1. Elija un dominio concreto y no todo el conjunto de datos, como la calidad de los ingresos, las operaciones de soporte, los canales de crecimiento o la elaboración de informes financieros. Escoja un área con un responsable claro y preguntas recurrentes.
  • Establecer una única fuente de verdad regulada. Las consultas pueden esperar hasta que el dominio cuente con conjuntos de datos canónicos, definiciones escritas de métricas, un responsable designado y monitoreo básico de actualidad.
  • Poner el nivel semántico en primer lugar y mantener SQL puro como solución de respaldo. Cuando una pregunta se relaciona claramente con un significado regulado, el agente no debería recurrir a tablas sin estructura.
  • Elaborar una única habilidad o guía que refleje cómo trabaja un analista competente en ese dominio: aclarar, seleccionar fuentes, validar, informar y citar de dónde provienen las cifras.
  • Reunir un pequeño conjunto de evaluación antes de expandirse. Veinte a treinta preguntas reales, con respuestas esperadas y casos límite conocidos, enseñan más que cien demostraciones internas.
  • Algo que hay que evitar es conectar directamente un modelo de vanguardia al sistema y llamarlo estrategia. Ese enfoque enseña poco más que cuán convincente puede sonar una respuesta incorrecta.

    Text-to-SQL ocupa un lugar en la estructura como una forma útil de ejecución. El problema es que se trata de un concepto demasiado limitado para describir todo el sistema. Este tema probablemente dividirá a los equipos en dos grupos: aquellos que consideran a Text-to-SQL como el producto final y aquellos que lo ven como una capa sencilla dentro de un flujo de trabajo analítico más amplio. Preguntas importantes: ¿de dónde provienen los mayores fallos (ambigüedad, recuperación de datos, obsolescencia o procesos débiles)? ¿Existen ya las bases que necesita un agente analítico, o el proyecto revelará deudas ocultas en el modelo de datos? ¿Qué tipo de recursos ofrece actualmente la capa de habilidades, ya sean prompts, guías de uso, ejemplos de SQL o listas de verificación para analistas?

    Apéndice: el plantilla completa de habilidades

    A continuación se muestra la plantilla completa de habilidades de Anthropic.

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