04 Investigar

Material do facilitador para 04 Investigar.

Duração

~20 minutos no total.

• 3 min — filtrar feedback negativo e verificar a raiz autoritativa do Chat.
• 4 min — criar três configurações de pontuação e a fila com anexos fixos.
• 4 min — codificar abertamente o comportamento antes do diagnóstico.
• 5 min — inspecionar evidências e executar SQL de policy-v1/policy-v2 lado a lado.
• 4 min — inserir correção, aprovar, concluir e registrar proveniência.

Preflight do instrutor

Antes da turma, confirme que o Módulo 03 produziu um chat_turn autoritativo com Boolean user-thumbs=false e sql-execution-success=true. Mantenha o ID privado e confira que a saída raiz contém pergunta, SQL, linhas e outcome.

Se precisar ensaiar, crie as configurações num projeto descartável, mas não a fila final. O conjunto de IDs anexados à fila fica fixo na criação, então crie primeiro as três configurações:

O exercício ocorre apenas na interface. Scripts verificam pontuações e depois promovem a exportação revisada, mas não criam a fila, escrevem julgamentos ou concluem a tarefa.

Roteiro de fala

1. Filtre Tracing por user-thumbs = false e associe o ID da planilha. Diga: “o feedback decide o que investigamos em seguida, não o que concluímos”.

2. Use Settings → Scores → Create para cada configuração. Em Annotations → Queues → Create, chame a fila de production-investigation-<session> com sufixo único e anexe as três.

3. Selecione a observação raiz chat_turn, abra Annotate e escolha a fila. Mostre a filha llm_call, mas explique que é o alvo errado: não contém resultado estruturado ponta a ponta nem é o incidente lógico.

4. Lembre que a preparação foi revelada, mas peça que suspendam esse conhecimento e codifiquem abertamente o observável. Uma boa nota inicial é:

   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. Só depois revele tudo: metadado policyversion=policy-v1, SQL/resultado baseado em cadastro e pontuações. O campo-fonte é policy_version; o adaptador emite policyversion.

6. Execute as definições lado a lado. A referência policy-v1 é:

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

   A referência atual policy-v2 é:

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

7. Só então aplique o diagnóstico: registre failure-category=stale-business-policy, mude Corrected Output para plain-text mode e cole a consulta atual bruta. O Langfuse não executa SQL; verifique o texto no cliente somente leitura antes de definir approved-for-golden=true e concluir.

8. Preserve source_trace_id, failure_category, source_policy_version, a correção e o ID opcional da tarefa para o Módulo 05.

Três diagnósticos tentadores, mas errados

• “O modelo ignorou o prompt.” O SQL segue policy-v1; a falha é a política implantada desatualizada.
• “sql-execution-success está quebrado.” O SQL executou, então true está correto; o evaluator não testa significado de negócio.
• “Um 👎 prova que o SQL está errado.” O feedback identifica um trace a revisar, mas não esclarece a intenção nem fornece consulta substituta verificada; comparação e revisão fazem isso.

Mantenha as alternativas visíveis até a codificação aberta. O instrutor conhece a resposta, mas deve modelar uma investigação real baseada em evidências.

Seleção da observação raiz

Há duas observações relevantes:

Se alguém adicionar a filha, não a conclua como investigação. Adicione o chat_turn raiz à fila correta e mantenha/exclua a tarefa equivocada segundo a retenção. Preserve o ID do trace, não o da observação filha, como source_trace_id.

Anexos fixos da fila e nomes seguros para repetição

O Langfuse fixa os IDs anexados na criação. Uma configuração omitida não pode ser acrescentada depois; crie todas primeiro. Configurações são mutáveis: alterações compatíveis exigem atualização auditada e não reescrevem pontuações existentes.

Use um sufixo seguro:

production-investigation-<session>-retry-1

Se houver omissão ou ID errado, crie nova fila com as três configurações, adicione novamente a raiz e marque a antiga como substituída (ou remova-a se a política permitir). Para editar configuração já anexada, use atualização auditada. Nunca reutilize um nome concluído de modo a ocultar qual tarefa decidiu.

Confiabilidade da saída corrigida

A correção vira verdade dourada futura; sintaxe e política importam. Mude Corrected Output para plain-text mode antes de colar SQL bruto. O Langfuse armazena, não executa; execute o texto exato pelo cliente da Etapa 6. Consulta malformada, em tabelas brutas, com várias instruções ou que falha deve continuar não aprovada.

Para SQL malformado:

1. defina ou mantenha approved-for-golden=false;
2. não conclua como aprovado;
3. corrija usando as views v_* permitidas;
4. execute e inspecione; e
5. só então aprove e conclua.

Se já foi concluída uma correção ruim, crie nova fila/tarefa com sufixo em vez de apagar a trilha de auditoria. A promoção do Módulo 05 também valida e executa SQL somente leitura, mas não substitui a revisão.

Falhas comuns

• Nenhum trace no filtro — confirme tipo Boolean e user-thumbs=false; associe o ID da planilha, não o diagnóstico curl.
• Alvo errado — a tarefa mostra só transcrição/SQL porque llm_call foi adicionada. Adicione chat_turn raiz.
• Dimensão ausente — crie nova fila com sufixo; não use formulário incompleto. Para edição compatível, atualize a configuração auditadamente.
• Metadado ausente — procure policyversion, não policy_version, e confirme a tag policy-v1.
• Contagens iguais — pare e repita o preflight do Módulo 03; não fabrique evidência.
• Correção formatada — use plain-text mode e apenas a consulta.
• Correção não executa — o Langfuse não detectará. Mantenha aprovação falsa, corrija e execute antes de concluir.

Conclusão e entrega

Antes do Módulo 05, confirme que a tarefa concluída aponta ao chat_turn autoritativo, a observação veio antes do diagnóstico, o SQL é exatamente o atual e a tarefa está aprovada. A planilha deve conter:

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>

A pontuação negativa permanece no trace como sinal de triagem. A anotação humana fornece a verdade revisada. O Módulo 05 preserva ambas as origens ao promover a correção e criar um evaluator preventivo.