assess-quality

name	assess-quality
description	Evaluar la cobertura actual de calidad del dato para un dominio completo, una tabla específica o una columna concreta. Devuelve un análisis de que dimensiones están cubiertas, cuales faltan y cuales columnas son prioritarias para nuevas reglas. Usar cuando el usuario quiera conocer el estado de la calidad de sus datos.
argument-hint	[dominio] [tabla (opcional)] [columna (opcional)]

Skill: Evaluación de Cobertura de Calidad

Workflow completo para evaluar el estado de la calidad del dato en un dominio, tabla o columna gobernada.

1. Determinación de Scope

Antes de ejecutar ninguna llamada MCP, determinar exactamente que se va a evaluar:

Si el dominio no está claro o hay que validar el domain_name: seguir guides/stratio-data-tools.md sec 5.1-5.2 para el workflow estándar de discovery. Si el dominio es técnico, usar search_domains(search_text, domain_type="technical") o list_domains(domain_type="technical") (ver guides/quality-exploration.md sec 1 para detalles de dominios técnicos). Tener en cuenta que el análisis semántico será más limitado en dominios técnicos: las descripciones de negocio, contexto de tablas y terminología pueden estar ausentes o ser parciales.

Determinar scope:

• Dominio completo: evaluar todas sus tablas
• Tabla específica: evaluar solo esa tabla
• Múltiples tablas: evaluar el subconjunto indicado
• Columna específica: evaluar una sola columna dentro de una tabla (requiere dominio + tabla + columna)

1.5 Comprobación de CDEs

Antes de lanzar la recopilación de datos, comprobar si el dominio tiene Elementos de Dato Críticos definidos. Esto determina el scope efectivo del assessment.

Llamar a get_critical_data_elements(domain_name=domain_name).

Si hay CDEs (critical_tables o columns_by_table no están vacíos):

• Informar al usuario: "Este dominio tiene Elementos de Dato Críticos definidos. El assessment se focalizará en los assets marcados como críticos."
• Construir el scope efectivo:
  • Tablas en critical_tables → evaluar todas sus columnas (la tabla entera es crítica)
  • Tablas en columns_by_table → incluir en el assessment, pero en la sección 3.2 (análisis de gaps) restringir a las columnas listadas para esa tabla; mencionar al usuario qué columnas son CDEs
  • Tablas que no aparecen en ninguna lista → excluir del assessment a menos que el usuario las haya pedido explícitamente
• Guardar en el contexto de trabajo: cde_mode=true, cde_full_tables (lista de critical_tables), cde_partial_tables (dict de columns_by_table)

Si no hay CDEs (tanto critical_tables como columns_by_table están vacíos o ausentes):

• Informar al usuario: "No hay Elementos de Dato Críticos definidos para este dominio. El assessment cubrirá todos los assets del dominio."
• Continuar con el workflow estándar (cde_mode=false).

Si la llamada falla (permiso denegado / 403, error MCP, herramienta no disponible):

• No bloquear el assessment. Informar brevemente al usuario — por ejemplo: "No se ha podido recuperar la lista de Elementos de Dato Críticos para este dominio (problema de permisos o servicio). Continuamos con el assessment completo del dominio."
• Continuar con el workflow estándar (cde_mode=false). En este caso se omite la columna CDE en las tablas de resultado.

Casos especiales:

• Tabla o columna específica pedida explícitamente por el usuario: si el asset pedido no aparece en ninguna lista CDE, evaluarlo igualmente según lo solicitado (la petición del usuario prevalece sobre el filtro CDE). Siempre mencionar si el asset es o no un CDE.
• Scope de columna específica: la comprobación CDE es solo informativa — evaluar la columna pedida con normalidad y mencionar si está o no marcada como Elemento de Dato Crítico.

2. Recopilacion de Datos (en paralelo)

Una vez determinado el scope, lanzar en paralelo. Es OBLIGATORIO incluir get_quality_rule_dimensions para entender que dimensiones soporta el dominio y sus definiciones.

Sobre dimensiones: ver sección 2 de guides/quality-exploration.md para entender por qué get_quality_rule_dimensions es obligatorio y cómo usar sus resultados.

Para dominio completo:

Paralelo:
  A. list_domain_tables(domain_name)
  B. get_quality_rule_dimensions(domain_name=domain_name)  <-- OBLIGATORIO
  C. quality_rules_metadata(domain_name=domain_name)           <-- actualizar metadata AI, solo si no se ejecutó antes

Luego, con la lista de tablas obtenida en A, lanzar en paralelo para TODAS las tablas:

Por cada tabla (en paralelo):
  get_tables_quality_details(domain_name, [tabla])
  get_table_columns_details(domain_name, tabla)
  get_tables_details(domain_name, [tabla])
  generate_sql("obtener todos los campos de la tabla [tabla] sin filtros", domain_name)

Finalmente, usar los SQLs generados para lanzar profile_data(query=[sql]) en paralelo.

Para tabla específica:

Paralelo:
  A. get_tables_quality_details(domain_name, [tabla])
  B. get_table_columns_details(domain_name, tabla)
  C. get_quality_rule_dimensions(domain_name=domain_name)  <-- solo si no se obtuvo antes
  D. get_tables_details(domain_name, [tabla])                  <-- solo si no se obtuvo antes
  E. generate_sql("obtener todos los campos de la tabla [tabla] sin filtros", domain_name)
  F. quality_rules_metadata(domain_name=domain_name)           <-- solo si no se ejecutó antes

Tras obtener E, lanzar profile_data(query=[sql]).

Para columna específica:

Paralelo:
  A. get_tables_quality_details(domain_name, [tabla])
  B. get_table_columns_details(domain_name, tabla)
  C. get_quality_rule_dimensions(domain_name=domain_name)  <-- solo si no se obtuvo antes
  D. generate_sql("obtener únicamente el campo [columna] de la tabla [tabla] sin filtros", domain_name)
  E. quality_rules_metadata(domain_name=domain_name)           <-- solo si no se ejecutó antes

Tras obtener D, lanzar profile_data(query=[sql]). En el análisis posterior (sección 3), filtrar todo al scope de esa columna: inventario de reglas que afectan a esa columna, gaps solo para esa columna, EDA solo de esa columna.

Nota sobre quality_rules_metadata: Esta llamada actualiza la metadata AI de las reglas (descripción, dimensión). Se ejecuta sin quality_rules_metadata_force_update — solo procesa reglas sin metadata o modificadas. Si falla, continuar sin bloquear: el workflow no depende de ella. Nota sobre permisos: esta tool requiere acceso de escritura; usuarios con roles de solo lectura recibirán un error 403. En ese caso, omitir y continuar — el assessment no se bloquea.

Nota: El perfilado (EDA) es fundamental para detectar gaps reales (ej: nulos existentes sin regla de completeness). Si el dominio tiene >10 tablas, evaluar primero las que el usuario mencione explícitamente y preguntar si quiere continuar con el resto.

3. Análisis de Cobertura

Con los datos recopilados (incluyendo el EDA de profile_data), analizar semánticamente la cobertura:

3.1 Inventario de reglas existentes

Usando los resultados de get_tables_quality_details (ya obtenidos en la fase 2), construir para cada tabla el inventario de reglas actualmente definidas:

• Nombre de la regla y dimensión que cubre (completeness, uniqueness, validity, etc.)
• Columna o columnas a las que aplica (inferido del nombre y la descripción de la regla)
• Estado actual: OK / KO / Warning y porcentaje de paso

Este inventario es la línea base: solo son gaps las dimensiones/columnas que NO están cubiertas por ninguna regla existente. Nunca proponer una regla que duplique una ya existente, aunque su estado sea KO (en ese caso, reportarla como regla a revisar, no como gap).

Si get_tables_quality_details devuelve lista vacía para una tabla: la tabla no tiene ninguna regla definida → todos los checks semánticos que se identifiquen en 3.2 son gaps.

3.2 Evaluación de gaps: Semántica primero, EDA como validador

El análisis tiene dos fuentes complementarias con roles distintos:

1. Análisis semántico (fuente primaria — determina QUÉ reglas deben existir)

La semántica del dominio es la base del razonamiento. Antes de mirar el EDA, estudiar en profundidad:

• Descripción del dominio: ¿qué representa este dominio de negocio? ¿qué garantías de calidad son inherentes a su naturaleza?
• Contexto de negocio de cada tabla (de get_tables_details): ¿qué proceso alimenta esta tabla? ¿qué uso se le da? ¿qué restricciones de negocio aplican?
• Semántica de cada columna (de get_table_columns_details): nombre, descripción, tipo de dato, si es obligatoria, si es clave, si es referencia a otro maestro
• Reglas de negocio documentadas: las restricciones ya descritas en la gobernanza del dominio son gaps inmediatos si no tienen regla asociada

Con esta lectura semántica, el modelo debe razonar por qué una columna necesita una dimensión concreta:

Columna ID / clave primaria     → completeness + uniqueness son obligatorios por definición
Columna importe / métrica       → validity (rango >= 0 o según negocio) es obligatorio
Columna fecha de negocio        → validity (rango lógico) y completeness si es campo clave
Columna estado / clasificación  → validity (enumerado con los valores permitidos del negocio)
Columna FK / referencia         → completeness si es obligatoria + consistency si hay maestro
Columna texto obligatorio       → completeness (por definición de negocio)
Columna texto libre / notas     → evaluación caso a caso; probablemente no necesita nada

2. EDA con profile_data (fuente secundaria — confirma y cuantifica)

Una vez determinadas semánticamente las reglas esperadas, el EDA sirve para:

• Confirmar que el problema existe realmente (un campo que debería ser no-nulo, ¿tiene nulos reales?)
• Priorizar gaps por impacto real: un 30% de nulos en un ID es más urgente que un 0,1%
• Parametrizar reglas de validity: los valores del EDA orientan rangos y enumerados (sin usarlos como límites exactos)
• Detectar gaps que la semántica no anticipaba: anomalías estadísticas que indican un problema de calidad no documentado

Uso del EDA por tipo de gap:
Completeness → ¿nulls > 0? Confirma el gap y da el % actual de fallo
Uniqueness   → ¿distinct_count < count? Confirma duplicados reales
Validity     → min/max/top_values orientan el rango o enumerado esperado
Consistency  → cruzar columnas relacionadas para detectar incoherencias

El EDA nunca es el motivo para NO proponer una regla que la semántica justifica. Si el EDA muestra 0 nulos en un ID, la regla de completeness sigue siendo necesaria: protege frente a futuros nulos. Si muestra el 100% de nulos en un campo supuestamente obligatorio, proponer la regla informando al usuario del estado actual.

Elevación de prioridad por CDEs: Si cde_mode=true y una tabla o columna es un Elemento de Dato Crítico, elevar la prioridad de su gap un nivel: MEDIO → ALTO, ALTO → CRÍTICO. Los assets CDE representan datos críticos para el negocio — cualquier dimensión desprotegida conlleva un riesgo de negocio mayor por definición.

Dominios técnicos — ajuste del análisis de gaps:

Cuando el dominio es técnico (descubierto vía list_domains(domain_type="technical")), las descripciones de negocio, contexto de tablas y terminología pueden estar ausentes o muy limitadas. En este caso:

• EDA pasa a ser la fuente principal de razonamiento: los patrones estadísticos (nulos, duplicados, rangos, distribuciones) son la base para identificar gaps.
• Razonar por nombres y tipos de columnas: usar convenciones habituales (*_id → clave/FK, *_date/*_dt → fecha, *_amount/*_amt → importe, *_code/*_status → enumerado) para inferir la semántica probable.
• Recomendaciones con menor confianza semántica: al no disponer de descripciones de negocio, las reglas propuestas deben marcarse como basadas en inferencia técnica. Validar las asunciones con el usuario antes de comprometerse con reglas de validity (rangos, enumerados) que requieren conocimiento de negocio.
• El flujo general (inventario → gaps → priorizar) se mantiene idéntico; solo cambia el peso relativo de las fuentes.

3.3 Cálculo del gap score

Para cada tabla, estimar:

• Reglas esperadas: suma de reglas que semánticamente deberían existir
• Reglas existentes: cuantas de las esperadas existen realmente
• Cobertura estimada: reglas_existentes / reglas_esperadas × 100

Presentar como estimación con razonamiento, no como cifra exacta. Usar rangos si hay incertidumbre ("entre el 40% y el 60% de cobertura").

4. Presentación del Resultado

Estructurar el output en el chat con las siguientes secciones:

Sección 1: Resumen Ejecutivo

Dominio/Tabla: [nombre]
Fecha evaluación: [hoy]
Modo de evaluación: CDEs activos — N tablas completamente críticas, M tablas con columnas CDE específicas | Evaluación completa del dominio (sin CDEs definidos)
Tablas analizadas: N
Reglas existentes: N
Cobertura estimada: XX% (razonamiento resumido)
Gaps identificados: N criticos, N moderados

Sección 2: Tabla de Cobertura por Dimensión

Para scope de dominio o tabla:

| Tabla | CDE | Completeness | Uniqueness | Validity | Consistency | Cobertura |
|-------|-----|-------------|------------|----------|-------------|-----------|
| account | CDE | Parcial (2/4) | OK | Gap | No aplica | ~50% |
| card | CDE* | OK | OK | Parcial | Gap | ~70% |
| order | — | Gap | No aplica | No aplica | No aplica | ~10% |

CDE = la tabla entera es un Elemento de Dato Crítico; CDE* = solo algunas columnas de la tabla son CDEs; — = no es CDE. Omitir la columna CDE cuando cde_mode=false (no hay CDEs definidos en el dominio).

Para scope de columna específica:

| Columna | Tipo | CDE | Completeness | Uniqueness | Validity | Consistency | Cobertura |
|---------|------|-----|-------------|------------|----------|-------------|-----------|
| customer_id | INTEGER | CDE | OK | Gap | No aplica | No aplica | ~50% |

Omitir la columna CDE cuando cde_mode=false.

Usar iconos para mayor legibilidad:

• OK / cubierta: indicar que hay regla y pasa
• Parcial: hay alguna regla pero no cubre todo lo esperado
• Gap: no hay regla donde debería haberla
• No aplica: esta dimensión no tiene sentido para esta tabla/columna
• KO/Warning: hay regla pero está fallando

Sección 3: Estado de Reglas Existentes

Para cada regla existente, mostrar en tabla:

| Regla | Tabla | Dimensión | Estado | % Pass | Observaciones |

Si una regla está en KO o WARNING, destacarla como acción prioritaria independientemente de los gaps.

Sección 4: Gaps Priorizados

Listar los gaps más importantes, ordenados por prioridad:

1. Claves primarias / IDs sin completeness o uniqueness (CRITICO)
2. Campos obligatorios de negocio sin completeness (ALTO)
3. Importes/métricas sin validity (ALTO)
4. Fechas sin validity (MEDIO)
5. Estados/clasificaciones sin validity (MEDIO)
6. Campos secundarios sin cobertura (BAJO)

Para cada gap indicar: tabla, columna, dimensión ausente, impacto potencial.

Sección 5: Recomendación de Próximos Pasos

Resumir que acciones se recomiendan:

• Si hay reglas KO/WARNING: resolver primero antes de crear nuevas
• Si hay gaps criticos: proponer crear reglas para cubrirlos
• Si la cobertura es buena (>80%): felicitar y mencionar mejoras opcionales

5. Pregunta de Continuación

Al finalizar, preguntar al usuario con opciones como quiere continuar, siguiendo la convención de preguntas al usuario:

• Crear reglas para cubrir los gaps identificados
• Generar un informe formal de cobertura
• Profundizar en una tabla concreta
• No hacer nada más

No proponer continuación automáticamente sin preguntar.