Análise de causa raiz para solicitações

Quando uma instrução falha, há várias causas possíveis. Alterar palavras aleatoriamente desperdiça tempo e pode corrigir o sintoma sem corrigir a causa raiz — levando à mesma falha em entradas ligeiramente diferentes.

Análise de causa raiz (RCA) é um processo sistemático para isolar o motivo específico pelo qual uma instrução falha, para que a correção resolva o problema real.

Cada falha de instrução remonta a uma de quatro causas raiz:

1. Problema de contexto: o modelo não possui as informações necessárias para responder corretamente
2. Ambiguidade da instrução: a instrução tem várias interpretações válidas, e o modelo escolheu a errada
3. Conflito de formato: duas partes da instrução fornecem instruções de formatação contraditórias
4. Limite de capacidade do modelo: a tarefa exige raciocínio ou conhecimento além do que este modelo consegue fazer de modo confiável

Um problema de contexto ocorre quando o modelo responde incorretamente porque a instrução não fornece as informações necessárias. O modelo preenche a lacuna com dados de treinamento — que podem estar desatualizados, incorretos ou ser alucinados.

Teste: forneça as informações ausentes diretamente na instrução e veja se a resposta melhora. Se sim, a correção é adicionar contexto (por exemplo, por meio de recuperação com RAG).

Ambiguidade da instrução ocorre quando a instrução pode ser razoavelmente interpretada de várias maneiras e o modelo escolhe a interpretação errada.

Exemplo: 'Resuma brevemente' — 'brevemente' significa uma frase, um parágrafo ou três itens com marcadores? O modelo tenta adivinhar. Teste: substitua a frase ambígua por uma especificação precisa e verifique se a falha é resolvida.

Um conflito de formato ocorre quando duas partes da instrução fornecem instruções contraditórias. O modelo precisa escolher uma e ignorar a outra — geralmente escolhendo a instrução mais recente ou mais destacada.

Exemplo: a instrução do sistema diz 'responda em texto simples', e a mensagem do usuário diz 'use markdown'. O modelo pode seguir qualquer uma delas, de modo inconsistente.

Uma falha de limitação de capacidade ocorre quando a tarefa realmente excede o que o modelo consegue fazer de modo confiável. Isso é diferente das outras três causas — nenhuma alteração na instrução a corrigirá completamente.

Sinais: a taxa de falhas é alta mesmo com instruções claras e contexto completo. Correções: use um modelo mais potente, divida a tarefa em etapas mais simples ou adicione uma etapa de verificação.

Para identificar qual causa raiz está ativa, use o isolamento sistemático:

1. Execute a instrução que falha e classifique o tipo de falha (resposta errada, formato etc.)
2. Adicione informações → se resolver: problema de contexto
3. Esclareça as instruções → se resolver: ambiguidade
4. Faça uma auditoria em busca de contradições → se resolver: conflito de formato
5. Atualize o modelo → se resolver: limitação de capacidade

Apenas uma correção deve ser necessária. Se forem necessárias várias correções, havia várias causas raiz.

A RCA segue dois modos:

• Eliminação: descartar as causas que são NOT responsáveis (teste cada hipótese e veja qual delas faz a saída NOT mudar)
• Confirmação: identificar a causa que, quando corrigida, resolve consistentemente a falha em várias entradas de teste

A confirmação exige pelo menos 3 entradas de teste. Uma correção que funciona em uma entrada, mas não nas outras, não resolveu a causa raiz — pode ter resolvido apenas um sintoma.

Depois de identificar a causa raiz, documente-a no registro de alterações da instrução. Inclua:

• Tipo de falha observado
• Categoria da causa raiz
• Hipótese testada
• Evidência (qual teste foi aprovado depois da correção)
• A alteração específica feita na instrução

Isso evita que futuros engenheiros investiguem novamente a mesma falha e permite reconhecer padrões entre diferentes instruções.

O erro mais comum na RCA é corrigir o sintoma em vez da causa. Exemplo:

• Sintoma: o modelo retorna JSON com um prefixo de texto adicional
• Correção errada: adicionar pós-processamento para remover o texto da saída
• Causa raiz real: não há instrução de formato no prompt + o modelo usa por padrão um estilo conversacional
• Correção correta: adicionar a instrução explícita "Retorne apenas JSON válido. Nenhum outro texto."

As soluções improvisadas de pós-processamento acumulam dívida técnica. As correções da causa raiz são duradouras.

Algumas falhas são intermitentes — a instrução funciona 80% das vezes, mas falha em 20%. Elas são mais difíceis de diagnosticar porque executar a instrução uma vez produz um resultado correto.

Abordagem: execute a instrução de 10 a 20 vezes com a mesma entrada. Se a taxa de falhas for diferente de zero, a instrução tem uma causa raiz probabilística — geralmente ambiguidade na instrução ou temperatura alta. Correção: torne a instrução mais específica ou reduza a temperatura.

As quatro categorias de causas raiz para falhas de instruções:

• Problema de contexto: o modelo não tem as informações necessárias — correção: adicione contexto via RAG ou injeção direta
• Ambiguidade da instrução: instrução vaga com várias interpretações — correção: adicione precisão
• Conflito de formato: instruções de formatação contraditórias — correção: consolide-as na instrução do sistema
• Limitação de capacidade do modelo: a tarefa excede a capacidade do modelo — correção: atualize o modelo ou decomponha a tarefa

Use o isolamento sistemático para testar cada hipótese. Confirme a correção em vários casos de teste. Documente as descobertas. Próxima lição: depuração sistemática por busca binária.