Critérios que separam de verdade

O Jev não adivinha a sua intenção: ele responde a pergunta escrita. A documentação lista “leitura literal” como o primeiro dos modos de falha conhecidos do jev-1.13, e isso significa que a maior parte do seu trabalho de qualidade acontece em dois campos de texto: instructions e criteria.

Esta página reúne o que a documentação oficial demonstra sobre esses dois campos, com os números que ela publicou, mais o que aprendemos escrevendo critérios em português.

O que o modelo recebe

Três fatos que mudam como você escreve:

1. O identificador da pergunta não é enviado. Chamar a pergunta de pediu_estorno não ajuda o modelo em nada. A pergunta completa precisa estar nas instructions.
2. Nomes de opção e descrições são enviados. Em um Choice, o modelo vê cobranca e vê o texto que explica o que é cobrança. Os dois carregam sentido.
3. Cada nível de um Score é julgado por si. O modelo não vê o número do nível nem os vizinhos. Escrever “pior que o nível anterior” não significa nada para ele.

O terceiro ponto tem demonstração publicada. Para um relato de botão desalinhado por poucos pixels, com níveis descritos apenas como 0, 1 e 2, a resposta saiu nota 0,57 com confiança 0,35, espalhada entre dois níveis. O mesmo relato, com os três níveis descritos por situação, saiu nota 0,00 com confiança 1,00. Números na descrição não ajudam; situações ajudam.

Descreva situações, não graus

“Moderadamente grave” não dá ao modelo nada com que comparar o texto. “Funcionalidade quebrada, mas existe contorno” dá.

A regra vale para qualquer primitiva. Compare:

{
  "gravidade_ruim": {
    "type": "score",
    "instructions": "Qual a gravidade do problema, de baixa a alta?",
    "criteria": ["Baixa", "Média", "Alta"]
  },
  "gravidade_boa": {
    "type": "score",
    "instructions": "Qual a gravidade do problema relatado?",
    "criteria": [
      "Cosmético; não afeta o funcionamento",
      "Funcionalidade degradada, mas existe contorno",
      "Bloqueio; não existe contorno"
    ]
  }
}

A segunda versão não é mais bonita: ela é respondível. Um texto pode ser comparado com “existe contorno”. Não pode ser comparado com “média”.

Separe o que se confunde

Quando duas opções vivem brigando, o problema quase nunca é o modelo: é que as descrições não dizem onde uma termina e a outra começa. A técnica recomendada é descrever a fronteira dos dois lados.

{
  "assunto": {
    "type": "choice",
    "instructions": "Qual é o assunto principal da mensagem?",
    "criteria": {
      "politica_de_estorno": {
        "cobre": "Perguntas sobre as regras: prazo, condições, quem tem direito",
        "nao_cobre": "Um pedido concreto de estorno já em andamento",
        "exemplos": ["Em quantos dias posso pedir estorno?", "Compra no débito dá direito a estorno?"]
      },
      "status_de_estorno": {
        "cobre": "Perguntas sobre um estorno específico já solicitado",
        "nao_cobre": "Dúvidas gerais sobre a regra",
        "exemplos": ["Meu estorno do pedido A-104 saiu?", "Faz dez dias e o dinheiro não voltou"]
      },
      "outro": "Nenhum dos assuntos anteriores"
    }
  }
}

A documentação autoriza essa estrutura de forma explícita: instructions, as descrições de opção de Choice, as descrições de nível de Score e os campos true e false de um Noul aceitam string, objeto, lista ou null. Os nomes dos campos internos são seus — cobre, nao_cobre, exemplos não são palavras reservadas, são rótulos que você escolhe para organizar o sentido.

E vale o contrário também: quando o nome da opção já basta, null é uma resposta honesta. {"calmo": null, "frustrado": null, "irritado": null} está correto.

Exemplos ajudam quando parecem com os seus dados

A documentação publica uma comparação que vale guardar. Sobre um relato de falha de exportação que funciona em outro navegador:

Duas leituras. A primeira: exemplo que se parece com a sua entrada real concentra a probabilidade e melhora a separação. A segunda, que a própria documentação faz questão de registrar: confiança maior não prova que a resposta está correta. Escolha exemplos cujo nível esperado você conhece e teste em casos separados antes de manter a mudança.

Alinhe instrução e critério

O sétimo modo de falha declarado da versão é justamente instrução e critério pedindo coisas diferentes. O caso extremo que a documentação cita: um Noul em que true significa “não” e false significa “sim” vai ter desempenho pior. Trate o critério como extensão da instrução, escrita na mesma direção, com a mesma linguagem.

Um teste caseiro que funciona: leia a instrução e os critérios em voz alta para alguém que não conhece o sistema. Se a pessoa hesita, o modelo também vai. A documentação usa uma versão disso: quando você olha uma resposta errada e se pega explicando o que realmente queria dizer, essa explicação é a metade que faltou na instrução.

Uma dimensão por pergunta

Se o critério mistura assuntos — “pontual e inteligente e experiente” —, a pergunta mede três coisas e nenhuma entrada consegue ser colocada. A confiança cai, e a nota passa a significar pouco. Separe em uma pergunta por dimensão e combine no seu código, normalizando cada nota pelo número do nível mais alto antes de aplicar pesos.

Outro detalhe do mesmo tipo: quando existe um caso extremo raro que exige ação diferente, ele merece nível próprio. Uma régua de irritação que termina em “muito irritado” não distingue o cliente irritado do cliente abusivo; acrescentar “conteúdo abusivo ou ameaçador” resolve, porque a ação do sistema é outra.

Em português, escreva em português

Nos nossos cinco testes de 18 de setembro de 2026, com critérios escritos em português, o caso de regionalismo nordestino (“oxe”, “num abre”) foi classificado como dúvida técnica com probabilidade 1,00 e confiança 1,00. Já a ironia — elogio literal com sentido oposto — derrubou a categoria para “outro”. A lição prática: critérios em português funcionam, e o lugar onde o desenho precisa de cuidado é onde a língua carrega sentido implícito.

Como a TypeSafe declara que o inglês é a língua principal de treino, teste no seu próprio conteúdo antes de automatizar. E se a dúvida for qual tipo de pergunta usar, comece por qual primitiva usar. Os limites que explicam boa parte dessas recomendações estão em os limites do jev-1.13.