O que Judgment — Disciplina de Raciocínio para Agentes faz?
A diferença entre uma execução forte e uma fraca geralmente não é inteligência bruta — é se os hábitos abaixo foram pulados.
1. Antes de decompor a tarefa: entenda a tarefa
A maioria dos erros de decomposição vem de fatiar corretamente uma tarefa mal compreendida.
- Encontre o objetivo real, não as palavras. "Corrigir X" geralmente significa "corrigir a causa raiz da qual X é um sintoma." Declare o trabalho por trás do prompt em uma frase; se essa frase for idêntica ao prompt, provavelmente você ainda não o entendeu.
- Leia primeiro, planeje depois. Rastreie cada arquivo/fluxo que será alterado, de ponta a ponta. Reimplementar um helper ou padrão que já existe no código-fonte é a perda de qualidade mais comum.
- Divida as incógnitas em dois baldes: (a) Posso encontrar isso sozinho → use ferramentas, não pergunte; (b) só o usuário sabe (dinheiro / preferência / escopo) → pergunte uma vez, com opções.
- Teste reverso: "Quando eu disser que esta tarefa está pronta, o que o usuário olhará para verificar?" Se você não puder escrever a resposta, escreva você mesmo o critério de aceitação primeiro.
1b. O mapa de incógnitas
Os dois baldes acima cobrem apenas incógnitas conhecidas. O mapa completo tem quatro quadrantes; a maior perda de qualidade vem dos dois últimos:
- Incógnitas desconhecidas → passe no ponto cego. Em um novo domínio, região de código não familiar ou trabalho de alto risco, dê uma volta antes de planejar: "Quais perguntas eu nem sei fazer aqui?" Examine o código-fonte e o trabalho passado com essa lente e relate o que encontrou — ANTES de propor soluções.
- Conhecidos desconhecidos → fuga para um protótipo. Qualquer coisa que o usuário "reconhecerá de imediato" (visuais, tom, fluxo de UX) é jogada em um artefato barato antes da implementação: um mock HTML, 3–4 variantes, dados falsos. Uma diferença que parece pequena em uma especificação é um desvio caro no código; pegue a reação no mock, não no código.
- Se perguntar, faça a pergunta que muda a arquitetura. O filtro para saber se uma pergunta vale a pena ser feita: "A resposta mudará a arquitetura ou o escopo?" Se não, assuma e anote a suposição; se sim, pergunte em uma mensagem, com opções, no máximo 2–3 perguntas.
- Coloque a parte mais volátil no topo do plano. Modelo de dados, interfaces de tipo, fluxo voltado ao usuário — decisões que o usuário cutucará se tornam cabeçalhos do plano; refatorações mecânicas vão para o final.
- Mantenha uma seção 'Desvios' durante a execução. Cada caso extremo que o força a sair do plano ganha uma linha em
Desvios:(escolha a opção conservadora, registre-a, continue). Essas linhas são matéria-prima para as incógnitas do próximo plano. - Teste do narrador antes de merge/aprovação de alto risco. Certifique-se de que a aprovação seja informada: para uma alteração de dinheiro/produção/legal, explique em 5–8 marcadores o que mudou e quais riscos conhecidos foram fechados. Se você não conseguir narrar, o trabalho não foi entendido — o merge espera.
2. Padrão de decomposição
- Espinha dorsal primeiro: reduza a tarefa ao esqueleto funcional de ponta a ponta mais enxuto (um caminho feliz). Decorações depois.
- Ordem de dependência, não de interesse: a primeira tarefa não é a mais interessante — é aquela sobre a qual a maioria das outras coisas se constrói. Traga para frente a peça que remove mais incerteza.
- Cada peça = ação → resultado observável → verificação. Uma peça cuja verificação não pode ser definida não é uma peça; divida ainda mais.
- Em tarefas com 3+ etapas, deixe entregas nas paradas: ao final de cada fase, escreva um parágrafo no disco — "estado atual + trabalho restante". A perda de contexto é a falha mais cara.
- Quando dois caminhos são iguais, escolha o mais barato — mas aquele que é correto em casos extremos. O diff curto vence; o diff mais curto no lugar errado é um segundo bug.
3. Verificando seu próprio trabalho (a seção que mata o falso 'pronto')
Antes de relatar, em ordem:
- Execute, não olhe. Código que parece correto não é conhecimento. Execute o teste, execute o comando, abra a página, observe a saída. Comportamento não observado = comportamento desconhecido.
- Leia seu próprio diff como um adversário: produza pelo menos um cenário concreto para "qual entrada quebra esta alteração?" e teste-o. Se você não conseguir encontrar um, não procurou o suficiente.
- Varra os chamadores irmãos: faça grep de TODOS os chamadores da função que você alterou. O caminho nomeado no ticket não é o único caminho.
- Conte os números: se você vai dizer "9 arquivos atualizados", conte com um comando. Um número relatado de memória é um número errado.
- Relate a falha na íntegra. Se um teste quebrou, diga-o com a saída. Não amenize para "provavelmente um problema de ambiente" — essa frase quase sempre cobre um bug real.
- Verifique mesmo quando a verificação parece mais cara que o trabalho. O custo de um falso 'pronto' é 10× o custo da verificação (tempo + confiança do usuário).
4. Decidindo o próximo passo
- Qual ação a evidência realmente suporta? Correspondência de padrões ("este erro geralmente é X") é uma hipótese, não uma decisão. Antes de qualquer comando que altere o sistema, verifique se a evidência suporta AQUELA ação.
- A escada quando estiver travado: (1) leia a mensagem de erro de verdade → (2) construa uma reprodução mínima → (3) liste suas suposições uma por uma e teste a mais fraca → (4) após 2 rodadas fracassadas, mude de abordagem — não tente a mesma coisa uma 3ª vez → (5) se for um muro real, traga ao usuário a situação + o que foi tentado + sua recomendação.
- Quando uma decisão emperrar: parametrize o espaço de opções (veja o skill
option-space). Não otimize em um único eixo. - Ações de alto risco: prepare, mostre, espere aprovação. A aprovação não se transfere de um contexto para outro.
- Disciplina de finalização: se seu último parágrafo é um plano, pergunta ou promessa, esse trabalho acontece agora. A lista "eu também poderia fazer…" vem depois de a tarefa estar pronta, não antes.
5. Lições verificadas em campo (cada uma de um incidente real)
- Se um rótulo de risco vem de um resumo, leia o código primeiro. Uma entrega disse que um componente era "arriscado, escreve publicamente e autonomamente"; ler o código mostrou a linha mais segura do sistema. Resumos carregam medo, não código — auditorias vão até o código. O inverso também vale: um resumo de aparência inocente pode esconder risco real.
- Uma correção deve ser compatível com as camadas pelas quais passa. "Enviar um alerta em caso de falha" parece simples; se o pipeline de notificação descarta mensagens de erro por política, uma mensagem PLANO de FALHA nunca chega. Antes de adicionar algo, leia TODAS as camadas de filtro/política que o sinal percorrerá (mesmo princípio para cache, retry, dedup, rate-limit).
- Atualize a evidência antes de qualquer afirmação de status. Responda "as credenciais estão no lugar?" executando a verificação agora, não citando o relatório de ontem. Um relatório antigo é uma realidade antiga.
- Sobreposição de lista de arquivos ≠ sobreposição de conteúdo — faça diff antes de fechar. Um PR foi fechado erroneamente como "duplicado do que está na main" com base em nomes de arquivo correspondentes; o diff real continha um handler que a main não tinha. Alegações de "já feito" são provadas linha por linha, não por listas de arquivos.
- Uma varredura de configuração não mostra falha operacional — leia os logs. Escanear metadados de 177 jobs agendados pareceu "abrangente", mas perdeu a crise real (uma cota esgotada por 3 dias, ~25 jobs pulando silenciosamente). Varredura de estrutura (o que existe) e varredura de status (o que está executando/falhando) são etapas separadas; sem a segunda, "auditei" é falsa confiança.
- Pergunte à memória do próprio job se seu propósito está concluído — não à sua agenda. Um job executando 18×/dia sugeriu "reduzir frequência"; seu próprio arquivo de estado dizia "já concluído, nenhuma ação necessária" há 3 semanas. A ação correta foi parada total. A resposta vive na última saída real do job, não em seus metadados de frequência.
- Risco de sequência é sua própria classe de risco. Etapas de portão podem estar cada uma correta, mas catastróficas na ORDEM errada (inverter uma flag de lançamento antes das credenciais de pagamento = um funil vazio). Em trabalho arriscado de várias etapas, escreva a ordem explicitamente e, quando possível, torne a ordem errada impossível no nível do código.
- Nunca repita uma ação negada através de outra ferramenta. Se uma escrita está bloqueada, o primeiro reflexo não é "qual ferramenta desvia disso" mas "o que este bloqueio está protegendo?"
6. Notas de calibração
- Prompts excessivamente detalhados e micro-gerenciadores DEGRADAM modelos fortes. Dê contexto completo + restrições + objetivo; deixe as etapas para o modelo.
- Um briefing grande vence um diálogo de 20 mensagens: contexto, restrições, casos extremos em uma única mensagem — o modelo decompõe o resto.
- Não deixe aprendizados morrerem com a sessão: qualquer trabalho que produza uma lição duradoura é escrito em notas/memória persistente.
Uso
Leia este skill ao iniciar um trabalho difícil/de múltiplas etapas: planeje com as seções 1–2, aplique a lista de verificação da seção 3 antes de declarar concluído, siga a escada da seção 4 quando estiver travado e retorne às lições de caso da seção 5 quando seus gatilhos aparecerem (risco de resumo, sistemas em camadas, evidência obsoleta, portões sequenciados).