04 Investigar

Punto de partida

El Módulo 03 produjo una traza autoritativa de Chat para How many active customers do we have? con una discrepancia intencionada:

Conserva el ID y la URL de la traza y los dos recuentos de referencia de la hoja de trabajo. No uses el diagnóstico curl sin valoración del Módulo 03.

Por qué es necesaria una investigación humana

Un pulgar hacia abajo indica al equipo dónde mirar, pero no qué ha fallado. El usuario podría referirse a otra cosa, la petición podría ser ambigua, el SQL generado podría ser inválido o podrían diferir dos definiciones de negocio. Promover directamente cada señal negativa a un dataset dorado convertiría suposiciones en verdad de referencia.

En este módulo, una persona revisora registra primero lo observable, prueba después las posibles explicaciones y solo entonces anota un diagnóstico y una corrección. Esa decisión revisada —no el pulgar hacia abajo— es la verdad de referencia que se entrega al Módulo 05.

Objetivo

Completar una tarea de anotación production-investigation-<session> para la raíz chat_turn del Módulo 03. La tarea debe incluir una observación, una categoría de fallo, el SQL corregido exacto, la aprobación para el dataset dorado y la procedencia de producción.

Paso 1 — Encontrar el incidente exacto de feedback

En Langfuse, abre Tracing y filtra por la puntuación Boolean user-thumbs = false. Abre la traza que cumpla todas estas condiciones:

• nombre u observación raíz chat_turn;
• pregunta How many active customers do we have?;
• el config_id ganador y el ID de traza registrados en el Módulo 03;
• metadata policyversion=policy-v1; y
• puntuaciones sql-execution-success=true y user-thumbs=false.

El código del servicio emite policy_version, pero el adaptador OpenTelemetry elimina el guion bajo, por lo que la clave de metadatos en Langfuse es policyversion.

Paso 2 — Crear las tres configuraciones de puntuación de la revisión

Esta configuración es deliberadamente un paso de revisión humana que solo se realiza en la interfaz. El repositorio del taller no contiene ningún comando que cree o complete esta tarea por ti.

Antes de crear la cola, abre Settings → Scores → Create y crea estas configuraciones:

Usa exactamente esos nombres y guiones. Crear primero las configuraciones es el flujo más seguro, porque el conjunto de ID asociado a una cola queda fijado al crearla. Si se omitió una configuración, crea otra cola con un sufijo nuevo. Las propias configuraciones son mutables: los cambios admitidos de nombre, esquema o categoría deben realizarse mediante una actualización auditada y no reescriben las puntuaciones existentes.

Paso 3 — Crear la cola y apuntar a la raíz lógica

Abre Annotations → Queues → Create y:

1. Llámala production-investigation-<session>, sustituyendo <session> por un identificador corto y único del taller.
2. Asocia las tres configuraciones del paso 2.
3. Crea la cola.
4. Vuelve a la traza del Módulo 03, selecciona su observación raíz chat_turn, abre el menú Annotate y elige esta cola.
5. Abre la tarea nueva y comprueba que el objetivo sea chat_turn, no llm_call.

No se pueden cambiar los ID de configuraciones asociados después de crear la cola. Recréala únicamente si ese conjunto es incorrecto; para un cambio admitido en una configuración ya asociada, usa una actualización auditada.

Paso 4 — Codificar abiertamente lo observable

El Módulo 03 reveló de forma deliberada el escenario preparado. Para esta investigación, deja entre paréntesis ese conocimiento y practica el flujo que seguiría una persona ante un incidente desconocido: inspecciona la pregunta, el SQL generado, el recuento devuelto, el modelo y prompt y ambas puntuaciones antes de nombrar la causa. Introduce en observed-issue una nota basada solo en pruebas, por ejemplo:

The answer returned a count and its SQL executed. The observed count differs from the
second reference count recorded in Module 03. The generated query uses a 90-day
customer signup window, and the trace metadata reports policy-v1.

Este texto aún no culpa al modelo, al motor SQL, al usuario ni a la política. La separación impide introducir de contrabando el diagnóstico preparado antes de comprobar las pruebas.

Paso 5 — Inspeccionar todas las pruebas de la traza

En la raíz chat_turn, verifica:

• metadata policyversion=policy-v1;
• el SQL generado usa v_customers y una ventana de 90 días sobre signup_date;
• el resultado estructurado contiene el recuento observado en el Módulo 03;
• la puntuación operativa es el Boolean sql-execution-success=true; y
• la señal de usuario es el Boolean user-thumbs=false.

El SQL generado es coherente con las instrucciones policy-v1 que proporcionó la versión publicada. La puntuación de ejecución correcta también lo es dentro de su alcance deliberadamente estrecho. En este momento, ninguno de los dos hechos demuestra si la política publicada coincide con la definición gobernada actual.

Paso 6 — Probar las dos definiciones de política en paralelo

Desde ClickHouse_Demos/workshops/agent_arena, ejecuta ambas definiciones de solo lectura en el mismo entorno:

source .env
.venv/bin/python - <<'PY'
from arena.config import load_config
from agents.chclient import ROClickHouseClient

queries = {
    "policy-v1": """SELECT count() FROM v_customers
WHERE signup_date >= today() - INTERVAL 90 DAY""",
    "policy-v2": """SELECT uniqExact(customer_id) FROM v_orders
WHERE order_ts >= now() - INTERVAL 30 DAY
AND status NOT IN ('cancelled', 'returned')""",
}
client = ROClickHouseClient(load_config().clickhouse)
for version, sql in queries.items():
    result = client.query(sql)
    print(f"{version}: {result.rows[0][0]}")
PY

Los dos recuentos deben coincidir con los valores de la hoja de trabajo y diferir entre sí. Ya tienes pruebas suficientes para diagnosticar una definición de negocio obsoleta en producción: la traza anuncia policy-v1, su SQL sigue esa política y la consulta actual verificada implementa policy-v2.

Paso 7 — Anotar, corregir, aprobar y completar

Vuelve a la tarea de anotación y registra:

Cambia Corrected Output al plain-text mode e introduce este SQL exacto sin formato:

SELECT uniqExact(customer_id) FROM v_orders
WHERE order_ts >= now() - INTERVAL 30 DAY
AND status NOT IN ('cancelled', 'returned')

Langfuse registra la corrección, pero no ejecuta el SQL. El cliente de ClickHouse de solo lectura del paso 6 debe haber ejecutado correctamente ese texto exacto antes de aprobarlo. Si modificas la corrección, vuelve a ejecutar el texto con el mismo cliente. Después elige Complete (o Complete + next). Una corrección mal formada, no ejecutable o sin verificar no debe aprobarse como verdad de referencia dorada.

Paso 8 — Registrar la procedencia para el Módulo 05

Copia estos valores en la hoja de trabajo. Mantén los ID privados dentro del proyecto del taller:

source_trace_id, failure_category y source_policy_version son obligatorios para un registro dorado derivado de producción. annotation_id es opcional en el runtime, pero regístralo cuando la interfaz lo muestre para mantener auditable la decisión.

Cómo verificar que has terminado

• Investigaste la única traza de Chat del Módulo 03 con user-thumbs=false.
• El objetivo de la anotación es la raíz chat_turn, nunca la hija llm_call.
• La cola se llama production-investigation-<session> y contiene las tres configuraciones con el tipo correcto.
• observed-issue registra el comportamiento antes del diagnóstico.
• Ejecutaste en paralelo el SQL obsoleto y el actual y confirmaste recuentos diferentes.
• La tarea completada registra stale-business-policy, el SQL corregido exacto y approved-for-golden=true.
• La hoja de trabajo conserva la procedencia de producción para el Módulo 05 sin publicar ID de trazas ni URL del proyecto.
• Puedes explicar por qué un pulgar hacia abajo prioriza una revisión humana, pero no se convierte por sí mismo en verdad de referencia.

Continúa con el Módulo 05 — Cerrar el ciclo para promover la corrección revisada, comparar versiones de política y evitar online la misma clase de fallo.