04 Investigar

Material del facilitador para 04 Investigar.

Duración

~20 minutos en total.

• 3 min — filtrar el feedback negativo y verificar la raíz autoritativa de Chat.
• 4 min — crear las tres configuraciones de puntuación y después la cola con asociaciones fijas.
• 4 min — codificar abiertamente el comportamiento observable antes de debatir un diagnóstico.
• 5 min — inspeccionar las pruebas de la traza y ejecutar en paralelo el SQL de policy-v1 y policy-v2.
• 4 min — introducir la corrección, aprobar, completar y registrar la procedencia.

Preflight del instructor

Antes de que lleguen los participantes, confirma que el Módulo 03 produjo el único chat_turn autoritativo con el Boolean user-thumbs=false y sql-execution-success=true. Mantén privado su ID de traza y comprueba que la salida raíz contiene la pregunta, el SQL generado, las filas devueltas y el resultado.

Si necesitas ensayar, crea las tres configuraciones de puntuación en un proyecto de prueba desechable, pero no crees por anticipado la cola final de los participantes. El conjunto de ID de configuraciones asociado a una cola queda fijado al crearla, así que el grupo debe crear primero las configuraciones y asociar las tres:

Este ejercicio de anotación se realiza únicamente en la interfaz. Los scripts de runtime pueden verificar puntuaciones de trazas y, más adelante, promover una exportación revisada, pero no crean la cola, escriben juicios humanos ni completan la tarea de anotación.

Guion

1. Filtra Tracing por user-thumbs = false y coteja el ID de traza con la hoja de trabajo del Módulo 03. Di: «El feedback decide qué investigamos después, no qué concluimos».

2. Usa Settings → Scores → Create para cada configuración. Después ve a Annotations → Queues → Create, llama a la cola production-investigation-<session> con un sufijo de sesión único y asocia las tres configuraciones.

3. Selecciona la observación raíz chat_turn, abre el menú Annotate y elige la cola nueva. Muestra el llm_call hijo, pero explica por qué es el objetivo equivocado: carece del resultado de ejecución estructurado de extremo a extremo y no es el incidente lógico al que se refiere el feedback.

4. Recuerda al grupo que el Módulo 03 reveló el escenario preparado; después pídeles que dejen ese conocimiento previo entre paréntesis y practiquen la codificación abierta de lo observable. Una buena primera nota es:

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

5. Solo cuando el grupo haya registrado esa nota, muestra todas las pruebas: los metadatos emitidos policyversion=policy-v1, el SQL basado en altas y su resultado, y las dos puntuaciones. El campo de origen es policy_version; el adaptador OpenTelemetry emite en Langfuse la clave saneada policyversion.

6. Ejecuta en paralelo las dos definiciones de política. La referencia de policy-v1 es:

   SELECT count() FROM v_customers
   WHERE signup_date >= today() - INTERVAL 90 DAY

   La referencia de la política actual policy-v2 es:

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

7. Solo tras esa comparación, aplica el diagnóstico: registra failure-category=stale-business-policy, cambia Corrected Output al plain-text mode y pega la consulta actual sin formato. Langfuse no ejecuta SQL, así que verifica el texto exacto con el cliente de solo lectura del paso 6 antes de establecer approved-for-golden=true y completar la tarea.

8. Conserva source_trace_id, failure_category, source_policy_version, la corrección y, opcionalmente, el ID de la tarea de anotación para el Módulo 05.

Tres diagnósticos tentadores pero equivocados

• «El modelo ignoró el prompt». El SQL de la traza sigue el contexto explícito de policy-v1. El fallo es la política obsoleta publicada, no una desobediencia a la instrucción proporcionada.
• «sql-execution-success no funciona». El SQL se ejecutó, así que el evaluator operativo devolvió correctamente true. Su diseño no comprueba el significado de negocio gobernado.
• «Un pulgar hacia abajo demuestra que el SQL es incorrecto». El feedback señala una traza que merece revisión. No desambigua la intención del usuario ni proporciona una consulta de sustitución verificada; para eso sirven la comparación de políticas y la revisión humana.

Mantén visibles estas alternativas hasta que los participantes hayan codificado abiertamente la traza. El instructor conoce la respuesta preparada, pero la investigación debe seguir modelando una revisión real basada primero en pruebas.

Selección de la observación raíz

La traza contiene dos observaciones relevantes:

Si alguien añade por error la hija, no la completes como investigación de producción. Añade la raíz chat_turn a la cola correcta y conserva o elimina la tarea errónea según la política de retención del proyecto. Guarda el ID de traza, no el ID de la observación hija, como source_trace_id.

Asociaciones fijas de la cola y nombres seguros para reinicios

Langfuse fija al crear una cola el conjunto de ID de configuraciones de puntuación asociados. No es posible añadir después una configuración omitida, por lo que lo más seguro es crear primero todas las configuraciones. Las propias configuraciones sí son mutables: los cambios admitidos de nombre, esquema o valores categóricos requieren una actualización auditada de la configuración, que no reescribe las puntuaciones existentes.

Usa un sufijo seguro para reinicios como:

production-investigation-<session>-retry-1

Si la cola omitió una configuración o asoció un ID equivocado, crea otra cola con sufijo y los tres ID correctos, vuelve a añadir la raíz autoritativa y marca claramente la cola anterior como reemplazada (o elimínala solo si la política del proyecto lo permite). Para un cambio admitido en una configuración ya asociada, usa la actualización auditada en vez de recrear la cola. Nunca reutilices el nombre de una cola completada de forma que oculte qué tarea proporcionó la decisión.

Fiabilidad de la salida corregida

La corrección se convertirá en verdad de referencia dorada, así que importan tanto la sintaxis como la política. Cambia Corrected Output al plain-text mode antes de pegar SQL sin formato. Langfuse almacena el texto, pero no lo ejecuta; antes de aprobarlo, ejecuta el texto exacto con el cliente de ClickHouse de solo lectura del paso 6. Una consulta que parezca correcta pero esté mal formada, use tablas sin procesar, contenga varias sentencias o falle en ClickHouse debe seguir sin aprobarse.

Para SQL mal formado:

1. establece o conserva approved-for-golden=false;
2. no completes la tarea como aprobada;
3. corrige la consulta para que use las vistas v_* permitidas;
4. vuelve a ejecutarla e inspecciona el resultado; y
5. aprueba y completa solo después de verificarla.

Si alguien completó una corrección mal formada, crea un nuevo sufijo de cola/tarea y repite la revisión en lugar de modificar silenciosamente el rastro de auditoría. El comando de promoción del Módulo 05 también valida y ejecuta SQL de solo lectura, pero esa protección no sustituye la revisión humana.

Fallos habituales

• No aparece ninguna traza tras filtrar — confirma que la puntuación es de tipo Boolean y que el filtro es user-thumbs=false; no busques un nombre de puntuación antiguo. Coteja el ID de la hoja de trabajo en vez de seleccionar el diagnóstico curl sin valoración.
• Objetivo equivocado — la tarea solo muestra transcripción/SQL porque se añadió llm_call. Vuelve a la traza y añade la raíz chat_turn.
• Falta una dimensión en la cola — la cola se creó sin el ID de una configuración requerida. Crea otra cola con sufijo; no continúes con un formulario de revisión incompleto. Para un cambio admitido en una configuración ya asociada, usa una actualización auditada en vez de recrear la cola.
• Los metadatos de política parecen ausentes — busca el campo emitido policyversion, no el campo de origen policy_version, y confirma después la etiqueta policy-v1 de la raíz.
• Los recuentos coinciden inesperadamente — detén el diagnóstico. Vuelve a ejecutar el preflight del escenario del Módulo 03 y no inventes pruebas a partir de una muestra de datos sin contraste.
• La corrección tiene formato en lugar de ser SQL sin procesar — cambia Corrected Output al plain-text mode y pega solo la consulta.
• La corrección no se ejecuta — Langfuse no lo detectará. Mantén la aprobación en false, corrígela y vuelve a ejecutar el texto exacto con el cliente del paso 6 antes de completar la tarea.

Finalización y entrega

Antes de pasar al Módulo 05, verifica que la tarea completada corresponde al chat_turn autoritativo, que la observación se registró antes del diagnóstico, que la corrección es el SQL exacto de la política actual y que la tarea está aprobada. La hoja de trabajo debe conservar:

source=production-feedback
source_trace_id=<authoritative Chat trace ID>
failure_category=stale-business-policy
source_policy_version=policy-v1
annotation_id=<task ID when available>

La puntuación negativa del usuario permanece en la traza de producción como señal de triaje. La anotación humana aporta la verdad de referencia revisada. El Módulo 05 conservará ambos orígenes al promover la corrección y crear un evaluator preventivo.