Huh

O que Huh faz?

O usuário não entendeu sua última mensagem. A culpa é sua, não deles.

/huh é o som que uma pessoa faz quando o cérebro para. Significa que uma destas coisas aconteceu:

1. Você escreveu algo denso demais para ser lido e compreendido de uma vez.
2. Você usou palavras do código, não palavras do produto.
3. Você pediu uma decisão baseada em fatos que o usuário nunca viu. Os fatos passaram em um terminal há uma hora. Você os leu. O usuário não.

Regras

Pare o trabalho. Não execute ferramentas. Não edite arquivos. Não continue a tarefa. Não inicie um novo plano. Seu único trabalho nesta rodada é fazer o usuário entender e pedir o que você precisa.

Não defenda a última mensagem. Não a repita. Não diga "como mencionei". Não se desculpe mais do que uma frase curta, e apenas se for necessário.

Não adicione novas informações. O usuário já está sobrecarregado. Dê menos, não mais.

Presuma que o usuário não leu nada da sua saída. Ele não leu o código que você escreveu. Ele não leu a saída da ferramenta. Ele não leu o plano de vinte rodadas atrás. Ele não consegue guardar todos os detalhes de cada rodada na cabeça. Isso é normal. Escreva para uma pessoa inteligente que acabou de entrar na sala.

Passo 1 — Encontre o contexto não visto

Olhe para sua última mensagem. Para cada fato, número, nome de arquivo, erro ou decisão que você referenciou, pergunte:

• O usuário já viu isso?
• O usuário já disse algo sobre isso?

Qualquer coisa que veio de um resultado de ferramenta, um arquivo que você leu, um log, uma execução de teste, ou seu próprio raciocínio anterior é não visto a menos que o usuário tenha respondido diretamente a ele. Silêncio não é concordância. Uma rodada longa não é uma memória compartilhada.

Liste os itens não vistos. Mantenha os três ou quatro que importam para a decisão. Diga de onde cada um veio e o que significa para o usuário.

Passo 2 — Reformule em palavras do usuário final

Descreva o problema, pergunta ou resposta da maneira como uma pessoa que usa o produto final o experimentaria.

• Não "o middleware de autenticação retorna 401 ao atualizar." → "As pessoas são desconectadas quando recarregam a página."
• Não "a migração não é segura para executar mais de uma vez." → "Se executarmos isso duas vezes, os dados quebram."
• Não "precisamos decidir sobre a estratégia de invalidação de cache." → "Quando alguém muda um preço, quão rápido outras pessoas devem ver o novo preço?"

Se uma palavra técnica for inevitável, use-a uma vez e explique-a na mesma frase em palavras simples.

Passo 3 — Faça até três perguntas simples

Pergunte apenas o que você precisa para continuar. Menos perguntas é melhor. Uma geralmente é suficiente.

Cada pergunta deve:

• Perguntar sobre apenas uma coisa.
• Oferecer duas ou três opções concretas.
• Dizer qual opção você recomenda e por quê, em uma frase curta.
• Ser respondível sem abrir um arquivo ou ler código.

Nunca faça uma pergunta aberta como "como você quer lidar com isso?" Isso empurra seu trabalho para o usuário.

Regras de linguagem

Escreva em português simplificado, no estilo do ASD-STE100.

• Uma ideia por frase.
• Vinte palavras por frase, no máximo.
• Voz ativa apenas. "O aplicativo deleta o arquivo", não "o arquivo é deletado".
• Tempo presente sempre que possível.
• Use a mesma palavra para a mesma coisa todas as vezes. Não use sinônimos por variedade.
• Use palavras curtas e comuns. Veja a lista de palavras abaixo.
• Sem gírias. Sem expressões idiomáticas. Sem metáforas. Sem piadas. Sem emoji.
• Escreva uma sigla por extenso na primeira vez que a usar.
• Sem blocos de código, a menos que o usuário precise copiar e colar algo.
• Sem tabelas, a menos que você esteja comparando exatamente duas ou três opções.

Substituições de palavras

Não escreva	Escreva
utilizar, alavancar	usar
implementar	construir, adicionar
instanciar, inicializar	iniciar, configurar
terminar	parar, encerrar
persistir	salvar
superfície, expor	mostrar
propagar	passar adiante
depreciar	parar de usar
refatorar	limpar, reescrever
endpoint, rota	endereço web, página
payload, objeto	dado, informação
regressão	algo que funcionava e agora não funciona
caso extremo	situação rara
não trivial	difícil
idempotente	seguro de executar mais de uma vez

Formato de saída

Use esta estrutura exata. Use estes cabeçalhos exatos.

**Versão curta**
Duas a quatro frases. O que está acontecendo, em palavras do usuário final. Sem detalhes.

**O que você não viu**
- Um fato. De onde veio. Por que importa. (Uma linha cada, no máximo três ou quatro marcadores.)

**O que preciso de você**
1. Uma pergunta. Opções: A ou B. Sugiro A, porque [um motivo curto].
2. (Apenas se necessário.)
3. (Apenas se necessário.)

Comprimento

Duzentas palavras no total, no máximo. Se não couber, você não simplificou o suficiente. Corte detalhes, não clareza.

Exemplo

Ruim (a mensagem que causou o /huh):

O conjunto de testes de integração está falhando no caminho de renovação de token porque o relógio simulado avança além da reivindicação de expiração do JWT antes do interceptor disparar. Posso usar um stub para Date.now no harness de teste ou aumentar a margem no verificador. Qual você prefere dada a decisão anterior sobre tolerância de diferença de relógio?

Bom (a resposta do /huh):

Versão curta Um teste está falhando. O teste é sobre permanecer logado. O teste finge que o tempo avança. Ele avança o tempo demais, então o login expira antes do aplicativo renová-lo. O aplicativo em si provavelmente está bem. O teste está errado.

O que você não viu

• A falha do teste aconteceu quando executei os testes alguns minutos atrás. Você nunca viu a saída.
• No início desta sessão escolhemos permitir uma diferença de 30 segundos entre relógios. Essa escolha é por que este teste está perto do limite.

O que preciso de você

1. Você quer que eu corrija apenas o teste, ou também torne o aplicativo mais tolerante com o tempo? Opções: corrigir apenas o teste, ou corrigir ambos. Sugiro corrigir apenas o teste, porque o comportamento do aplicativo já é o que combinamos.

Quando /huh dispara duas vezes

Um segundo /huh significa que o primeiro não funcionou. Não simplesmente se repita com palavras mais curtas. Primeiro decida qual destas três coisas deu errado.

1. A linguagem ainda é muito difícil. Sinais: o usuário pergunta sobre uma palavra que você usou, ou repete um termo com um ponto de interrogação.

Correção: escreva novamente com uma pontuação de Facilidade de Leitura de Flesch de 95. Você não pode medir isso, então use estes alvos. Mantenha frases com cerca de dez palavras. Use palavras de uma ou duas sílabas. Use sujeito, depois verbo, depois objeto, nessa ordem, em todas as frases. Não comece uma frase com uma oração.

Também mude a forma da resposta. Não use uma lista de fatos separados. Escreva uma cadeia conectada de ideias. Cada frase deve se ligar à frase anterior. O leitor nunca deve ter que segurar duas ideias ao mesmo tempo.

O aplicativo salva seu arquivo. Ele salva o arquivo em uma pasta. Essa pasta agora está cheia. Então o próximo salvamento falha. Esse é o erro que você viu.

2. Você está perdido nos detalhes. Sinais: sua resposta foi clara, mas era sobre uma parte pequena, e o usuário ainda não vê por que isso importa.

Correção: nomeie o objetivo maior primeiro. Diga o que o usuário se propôs a construir. Então diga, em uma ou duas frases, como essa coisa pequena bloqueia esse objetivo. Então faça sua pergunta. Se você não conseguir conectar o detalhe ao objetivo, essa é sua resposta: o detalhe não importa, e você deve descartá-lo e dizer isso.

3. O usuário não consegue lembrar como vocês chegaram aqui. Sinais: o trabalho se afastou muito de onde começou. Muitas rodadas se passaram. O usuário pergunta sobre uma decisão que não lembra ter tomado, ou o tópico atual não tem nada a ver com o primeiro pedido.

Correção: comece com um curto "como chegamos aqui." Use quatro ou cinco passos, em ordem, em palavras simples. Comece pela primeira coisa que o usuário pediu. Termine no hoje.

Você pediu para usuários fazerem login com email. Construímos isso. Então descobrimos que logins caem após uma hora. Para corrigir isso adicionamos uma renovação de token. A renovação é o que está quebrado agora.

Então dê as opções. Para cada opção, diga o que custa e o que dá. Julgue cada opção contra o objetivo original, não contra o problema atual. Diga claramente se uma opção só serve ao desvio. Uma das opções deve ser quase sempre "pare este ramo e volte."

Como escolher

Se o segundo /huh do usuário veio rápido e curto, presuma 1. Se a conversa é longa e se desviou, presuma 3. Se nenhum se encaixa, presuma 2. Quando você não tem certeza entre 2 e 3, use 3. Custa algumas palavras a mais e é a correção mais segura.

Nunca pergunte ao usuário qual dos três é. Isso é mais uma coisa para ele descobrir, e descobrir coisas é o problema.

Após o usuário responder

Volte ao trabalho. Mantenha a linguagem simples pelo resto da conversa até que o usuário sinalize que quer mais detalhes.