hunt

Visão geral da skill hunt

Para que serve o hunt

hunt é uma skill de debugging-first que força o raciocínio de causa raiz antes de aplicar qualquer correção. É ideal para erros, crashes, regressões, testes com falha, problemas de cache desatualizado, bugs de screenshot e falhas do tipo “funcionava antes”, em que você precisa de uma hipótese testável, não de um patch rápido.

Quem deve instalar

Instale a skill hunt se você costuma depurar entre código da aplicação, testes, artefatos de build ou comportamento em runtime e quer um guia de hunt repetível para estreitar o problema rápido. Ela é especialmente útil quando os sintomas são ruidosos, as tentativas de correção continuam falhando ou o bug atravessa logs, estado da UI e saída gerada.

O que torna o hunt diferente

O valor central é disciplina: identificar um arquivo, função, linha ou condição específicos e depois reunir evidências até que a causa raiz fique defensável. As referências de apoio cobrem logging, padrões de falha, casos-limite de IME/Unicode e bugs de renderização, então a skill não é só “depure melhor”; ela empurra você para o tipo certo de diagnóstico.

Como usar a skill hunt

Instalação e preparo de contexto

Use o fluxo normal de instalação da skill no seu ambiente e depois abra os arquivos da skill nesta ordem: SKILL.md, references/failure-patterns.md, references/logging-techniques.md, references/ime-unicode.md e references/rendering-debug.md. Comece pela referência que corresponde ao sintoma; não leia tudo, a menos que o problema atravesse mais de um domínio.

Como pedir uso do hunt

Para obter o melhor uso do hunt, peça diagnóstico antes de reparo e inclua o menor sintoma reproduzível que você tiver. Um bom pedido soa assim: “use hunt para este regression: clicar em Save não persiste depois do refresh; a mudança mais recente mexeu em src/hooks/user.ts; os logs mostram cache hit.” Um pedido fraco soa assim: “o save quebrou, conserte.”

Fluxo de trabalho que a skill espera

O guia hunt espera que você declare uma hipótese em uma frase, valide com evidências e só então aplique um patch quando a causa puder ser testada. Na prática: reproduza, restrinja o caminho, colete um log ou uma verificação que discrimine a causa, confirme o trajeto de propagação e, em seguida, escreva a menor correção possível e um teste de regressão, se der.

Leitura prática por referência

Use references/failure-patterns.md quando o bug tiver cara de problema de cache, fila, guard ou fronteira de build. Use references/logging-techniques.md quando você precisar de evidência instrumentada. Use references/ime-unicode.md para bugs de input CJK ou composição. Use references/rendering-debug.md para falhas de PDF, impressão, fonte ou layout.

FAQ da skill hunt

O hunt serve só para bugs de código?

Não. A skill hunt serve para depurar qualquer modo de falha concreto: erros em runtime, testes com falha, artefatos gerados quebrados, regressões de UI e divergências de saída. Ela não é a melhor opção para revisão de código pura ou design de funcionalidade.

Preciso saber a causa raiz exata antes?

Não, mas você precisa de uma hipótese que possa ser falsificada. A skill foi feita para ajudar você a sair de “algo está errado” para “acredito que a causa raiz é X porque Y”.

O hunt é melhor do que um prompt normal?

Normalmente sim quando a falha é ambígua ou recorrente. Um prompt genérico pode gerar um patch; hunt tenta reduzir o chute primeiro, o que diminui a chance de uma correção quebrar outro caminho.

Quando não devo usar o hunt?

Evite usar quando você estiver adicionando uma nova funcionalidade, refatorando sem bug ou já tiver uma correção mínima confirmada e só precisar de ajuda de implementação. Também não é a melhor escolha para brainstorming de arquitetura em alto nível.

Como melhorar a skill hunt

Traga evidências mais fortes desde o início

Informe o sintoma, a mudança mais recente, o ambiente exato e uma ou duas observações concretas. Por exemplo: “falha só no cold start”, “passa depois de limpar o cache”, “quebra no macOS com input CJK” ou “o PDF renderiza localmente, mas não no CI”. Isso ajuda o hunt a escolher o padrão de falha certo imediatamente.

Evite modos de falha comuns

O maior erro é pedir uma correção antes de delimitar a causa. Outro erro comum é ter observabilidade vaga: logs que mostram só a mensagem de erro, e não a branch, a sequência ou a transição de estado que diferencia uma hipótese da outra. Traga evidência discriminante, não mais ruído.

Itere depois da primeira passada

Se o primeiro diagnóstico estiver incompleto, responda com a nova observação em vez de reiniciar o prompt inteiro. A skill hunt funciona melhor como um ciclo de refinamento: hipótese, verificação, contraexemplo, hipótese mais forte. É assim que você sai da instalação da skill hunt para uma busca de debugging realmente confiável.