Skip to content

Guía para el agente

Estos archivos son tu fuente de contexto para explicarle a un ingeniero cómo funciona un proceso de datos. El ingeniero suele preguntar en sentido inverso: parte de algo que ve (un dashboard, un campo del frontend, una tabla) y quiere saber de dónde sale y dónde está la lógica.

Cómo responder

  1. Identifica el punto de consumo en la pregunta (tabla, dashboard, campo, feature del frontend).
  2. Búscalo en index.md, sección "Veo esto → empieza acá", o por keywords en el frontmatter de cada ficha.
  3. Abre la ficha del proceso y recorre el linaje hacia atrás: consumo → modelo dbt (lógica) → tabla RAW → ingesta → fuente.
  4. Distingue siempre dos capas:
  5. Ingesta (Cloud Run, Pub/Sub, Dataflow, Airbyte, Datastream): mueve el dato, no aplica lógica de negocio.
  6. Lógica (modelos dbt): dedup, redondeos, joins, conversiones, reglas. Si el ingeniero pregunta "por qué este número es así", la respuesta casi siempre está en un modelo dbt.
  7. Cita recursos exactos: nombre de tabla con proyecto (solvento-…-prod.dataset.tabla), nombre del job/topic/servicio, y el archivo del modelo dbt + repo donde está la lógica.
  8. Si la ficha no existe o el dato no está mapeado, dilo explícitamente y sugiere buscar el modelo en dbt-etls/dbt-analytics; no inventes linaje.

Estructura que puedes parsear

Cada ficha tiene frontmatter YAML con: proceso_id, keywords (sinónimos de entrada), raw (tablas + quién las carga), logica_dbt (modelos con archivo, salida y qué hace), consumo (quién lee y de qué tabla), repos, criticidad. Usa esos campos para recorrer el linaje sin tener que leer todo el cuerpo.

Ejemplo

Ingeniero: "El front de Terminal muestra tarifas de un mes viejo, ¿de dónde sale ese dato y dónde está la lógica?"

Respuesta esperada: el front pide los datos a solvento-api, que ejecuta cards de Metabase cuyos IDs por ambiente viven en flux/app-config (apps/<env>/solvento-api-values.yaml, DATA_ACCESS_QUESTION_ID_*). Esas cards leen solvento-risk-analytics-prod.terminal_v3.datarelease_<fecha>, materializada por el pipeline SQL del repo terminal (releases/<fecha>/sql/, corrido a mano con make), que a su vez lee los modelos de dbt-analytics (analytics_engineering_core.fact_syntage_invoices*, analytics_engineering_intermediate.int_carta_porte). El orden de diagnóstico es: primero MAX(departure_month) en la tabla, recién después el question ID del ambiente. Ver Terminal v3. La lógica de negocio está en dbt y en el SQL del release, no en la ingesta.