Módulo 0.1 · o método

Encontre primeiro as falhas que importam

Imagine que seu assistente de IA dê uma resposta ruim. Faltou uma fonte, a busca na base de conhecimento falhou ou o assistente recusou um pedido razoável? Antes de criar uma verificação, examine os registros que o sistema já produziu e procure padrões. O software pode agrupar falhas parecidas; você decide quais grupos exigem uma ação.

o que você vai conseguir fazer Ao final deste módulo você pode mapear os modos de falha reais do seu sistema com um juiz de descoberta e decidir quais precisam de uma verificação que bloqueie o lançamento (um gate).

Neste curso, um harness é a estrutura repetível de verificação de lançamento: ela executa as verificações escolhidas, guarda a evidência e aplica a consequência. Este primeiro módulo fornece o mapa inicial de falhas.

A armadilha: criar juízes para falhas que você nunca mapeou

Uma equipe pode começar pela falha de que mais ouviu falar, como uma resposta inventada. Seus próprios registros podem mostrar outro problema: talvez chamadas de ferramenta falhem em silêncio com muito mais frequência. Se a equipe criar verificações antes de olhar esses registros, pode gastar tempo no problema errado. Comece pelos padrões que realmente aparecem. Depois compare a frequência e o dano de cada um.

o movimento A entrada, a saída e a atividade de ferramentas registradas em uma execução formam um registro de execução. Um juiz de descoberta examina uma amostra desses registros e reúne falhas parecidas. Ele não aprova nem reprova o lançamento. Entrega uma lista curta dos tipos de falha, suas contagens e um exemplo de cada um, para que uma pessoa escolha o que investigar primeiro.

A decisão continua humana

Quando há mais registros do que uma pessoa consegue examinar, o juiz de descoberta faz a primeira triagem. Depois, uma pessoa analisa a lista bem menor: quais grupos são problemas reais, quais resultam de rótulos errados e quais podem esperar? O software cuida do volume. A pessoa continua responsável por decidir o que deve bloquear um lançamento.

o humano continua definindo o padrão O harness não substitui você. Ele automatiza a parte repetitiva da revisão: ler registros e executar verificações a cada mudança. Você continua definindo a direção: quais grupos representam falhas reais, quais importam e qual é o critério de aprovação. O que deixa de fazer é a leitura manual e repetitiva, que não acompanha o volume de produção.

nosso exemplo em andamento — o bot de suporte fundamentado em recuperação Do módulo 0.1 ao 0.9, usaremos o mesmo sistema fictício para formar uma única história: um bot de suporte que consulta uma base de conhecimento antes de responder às perguntas dos clientes. É desse sistema que você analisará os registros. Seus modos de falha — respostas sem citação, buscas na base que falham sem aviso e recusas desnecessárias — são aqueles que o juiz de descoberta abaixo identifica. No 0.3 você escreverá juízes para eles; no 0.5 você aplicará um gate neles; no 0.9 você conectará todo o harness em torno deles. (Um padrão, não um benchmark — você constrói e mede o seu próprio.) Os percentuais abaixo pertencem somente a este retrato didático fictício de 500 registros. O laboratório executável usa um fixture separado de 12 registros e retorna quatro modos; suas contagens não passam para este bot.

antes de prosseguir — quais registros um juiz de descoberta deve examinar primeiro?

Uma amostra de registros de produção — entrada, saída e metadados de ferramenta ou erro —, não um conjunto de avaliação previamente selecionado. A descoberta procura entender como o sistema realmente falha em uso; um conjunto escolhido à mão pode distorcer a frequência aparente dos diferentes tipos de falha.

O juiz de descoberta em ação

Ele recebe registros, propõe rótulos para os modos de falha, atribui cada registro a um modo — ou o marca como "limpo" — e retorna a taxonomia com contagens e um exemplo por modo — a evidência que você examinará rapidamente.

A lista ordenada orienta a decisão: compare a frequência de cada falha com o dano que ela pode causar. Uma falha rara e grave pode merecer um gate antes de outra frequente e de baixo impacto.

def discover_failures(traces, discovery_judge):
    labeled = []
    for t in sample(traces, n=500):          # o juiz examina o volume; você revisa o resumo
        mode = discovery_judge(t)             # {"mode": "silent_tool_error", "evidence": span}
        labeled.append(mode)
    taxonomy = cluster(labeled)               # ordenado: mode -> (count, example)
    return taxonomy                           # VOCÊ revisa os modos, não cada registro bruto

Agora — e apenas agora — você escolhe os tipos de falha prioritários e, nos próximos módulos, transforma cada um em um juiz com um veredito, evidência e um limite. A descoberta prioriza o trabalho; o harness aplica os critérios definidos.

das contagens a um quadro resolvível

Uma taxonomia ordenada mostra com que frequência cada modo aparece. Um quadro estratificado mantém uma linha por grupo de falha, em vez de misturar todas as decisões em uma média.

Verdadeiro positivo (TP): o avaliador identifica uma falha real.
Falso positivo (FP): ele dispara um alarme falso em um caso limpo.
Falso negativo (FN): ele deixa passar uma falha real.

Precisão pergunta quantos alertas estavam corretos: TP / (TP + FP). Revocação pergunta quantas falhas reais foram encontradas: TP / (TP + FN).

Exemplo resolvido de citação ausente. Entre 10 casos reais sem citação, o avaliador identifica 4 e deixa passar 6; ele também sinaliza 2 casos limpos. Portanto, TP=4, FP=2 e FN=6. A precisão é 4 / (4 + 2) = 0.67; a revocação é 4 / (4 + 6) = 0.40. Uma acurácia combinada alta ainda pode esconder essa baixa revocação.

Repita essa linha para cada grupo de falha e compare frequência, gravidade, precisão e revocação antes de escolher um gate. Depois examine os grupos prioritários: três rótulos são variantes superficiais de uma causa ou falhas realmente diferentes? As contagens localizam o trabalho; o quadro torna visíveis os erros do avaliador.

caso na prática Em um fluxo de vídeo operado por uma única pessoa, o mesmo movimento funciona: uma passagem de descoberta identifica os modos de falha que realmente recorrem — deslocamento de sincronização labial, quebras de persona — e um operador decide quais se tornam gates rígidos. Uma pessoa define o critério; verificações automatizadas o aplicam repetidamente e devolvem casos incertos para revisão. (Este é um método, não um benchmark: use o exercício prático para construir e medir o seu.)

por que a descoberta deve ser recorrente — mudança de critério Um juiz de descoberta é ele próprio um modelo de linguagem de grande porte (LLM): um modelo instruído a classificar ou explicar texto. Juízes LLM não mantêm seus critérios fixos. Shankar et al., "Who Validates the Validators?" (arXiv 2404.12272, UIST '24), documentam a mudança de critério: avaliadores baseados em LLM aplicam a rubrica de forma inconsistente e a alteram durante a anotação, afastando-se do critério que deveriam codificar. A consequência é direta: não execute a descoberta uma única vez nem confie indefinidamente na taxonomia. Repita-a periodicamente e trate os grupos ordenados como um retrato temporário.

por que agrupar falhas antes de escrever qualquer juiz?

Porque exemplos observados mostram quais tipos de falha merecem investigação. Sem essa evidência, a equipe pode criar verificações para um problema marcante, mas pouco prioritário. Repita a descoberta periodicamente porque o uso e os critérios do juiz podem mudar.

um grupo reúne 40% das falhas de baixa gravidade; outro, com 3%, causa perda de clientes. Qual deve receber um gate primeiro?

Nenhuma decisão segue apenas da contagem. A descoberta lhe dá o mapa; você ainda combina frequência, gravidade e precisão/revocação por grupo para decidir o que merece um gate. As contagens são o início, não o veredito.

exercício de decisão sem código Um assistente de agendamento informa horário errado em 8% dos registros amostrados e expõe uma anotação privada em 1%. Sem código, escolha a primeira falha a bloquear e declare a evidência que registraria.

compare sua decisão com o feedback

Bloqueie primeiro a anotação privada exposta. A frequência menor não elimina o dano maior; registre o caso, o trecho exposto e a decisão de lançamento. Rejeite a alternativa plausível de bloquear o horário errado por ser mais frequente: frequência ordena a investigação, mas não define a gravidade sozinha.

como interpretar o resultado Um agrupamento de falhas repetidas justifica investigar primeiro aquele fluxo porque ele aparece em vários casos revisados. Isso não estima prevalência nem prova a causa; confirme o padrão em casos mais amplos antes de transformá-lo em regra de lançamento.

▶ extensão técnica opcional · laboratório executável

failure-discovery

Aplique um juiz de descoberta a uma pasta de registros e obtenha uma taxonomia ordenada de falhas, com contagens e exemplos. Execute-o sobre a amostra incluída e depois use seus próprios registros.

labs/failure-discovery/ · python discover.py --lang pt

pontos-chave

Mapeie falhas antes de construir juízes — proteja primeiro o modo que realmente domina o risco.
Um juiz de descoberta agrupa uma amostra previamente definida de registros; você revisa os grupos e os exemplos de cada grupo.
As contagens são apenas o início: adicione métricas por grupo, com estratificação, e faça uma análise de erros antes de decidir a quais falhas aplicar um gate.
O humano define o critério (o que é real e o que importa); os juízes o aplicam a tudo.