debugger

Visão geral da skill debugger

Para que serve a skill debugger

A skill debugger é um fluxo estruturado de depuração para encontrar causas raiz mais rápido do que um prompt genérico do tipo “o que há de errado?”. Ela foi pensada para casos em que o código lança erros, se comporta de forma inesperada, sofre regressões após mudanças ou falha apenas em certos ambientes. Em vez de pular direto para uma correção, a skill debugger impõe uma sequência que faz diferença no trabalho real de Debugging: reproduzir, isolar, analisar, corrigir e verificar.

Quem deve instalar esta skill debugger

Esta skill debugger atende bem desenvolvedores, agentes de IA para código e times técnicos que querem um processo repetível de Debugging, e não um troubleshooting improvisado. Ela é especialmente útil se você costuma trabalhar a partir de stack traces, logs, relatos de bug incompletos ou passos de reprodução incertos. O foco aqui é menos em expertise profunda de um framework específico e mais em melhorar a disciplina de depuração entre projetos.

Qual trabalho ela ajuda você a realizar

O verdadeiro job-to-be-done não é “explicar uma mensagem de erro”. É transformar uma falha vaga em um caminho claro de investigação: o que mudou, como reproduzir, onde reduzir o escopo, quais evidências coletar e como validar a correção final. Isso torna a instalação da skill debugger mais valiosa quando o time está perdendo tempo com suposições ou corrigindo sintomas repetidamente em vez da causa.

Por que esta skill debugger se destaca

O diferencial útil está no seu formato operacional. O repositório inclui:

• um fluxo de depuração em fases em SKILL.md
• apoios rápidos de consulta para depuração em references/checklist.md, references/errors.md e references/patterns.md
• um gerador prático de relatórios em scripts/debug_report.py

Essa combinação torna a skill debugger mais adequada para trabalho ao vivo, em estilo de incidente, do que um simples template de prompt. Ela entrega processo, checklist, categorias comuns de falha e um artefato de handoff.

O que ela não tenta fazer

Isto não é um debugger específico de linguagem, uma extensão de IDE nem uma plataforma de tracing. Não vai substituir ferramentas de runtime, profilers ou a documentação do framework. Se sua principal necessidade é stepping interativo, inspeção de memória ou tracing em nível de protocolo, use essas ferramentas diretamente e trate este guia debugger como a camada de raciocínio ao redor delas.

Como usar a skill debugger

Contexto de instalação e caminho no repositório

A skill fica em skills/debugger dentro de zhaono1/agent-playbook. Se você usa um loader de skills com suporte a fontes do GitHub, instale a partir do repositório e aponte para a skill debugger. Um padrão comum é:

npx skills add https://github.com/zhaono1/agent-playbook --skill debugger

Se a sua configuração for diferente, o importante é carregar o diretório skills/debugger para que o agente consiga acessar SKILL.md e também os arquivos de apoio em references/ e scripts/.

Leia estes arquivos primeiro

Para adotar rápido, leia nesta ordem:

1. skills/debugger/SKILL.md
2. skills/debugger/references/checklist.md
3. skills/debugger/references/patterns.md
4. skills/debugger/references/errors.md
5. skills/debugger/scripts/debug_report.py

Esse caminho espelha o uso real da skill debugger: primeiro o fluxo, depois as heurísticas de investigação, depois as categorias de erro e por fim o suporte de documentação.

Como a skill debugger é acionada na prática

O repositório foi desenhado para ser ativado quando o usuário relata:

• um erro ou exceção
• comportamento inesperado
• “debug this”
• “why isn’t this working?”

Na prática, a skill debugger funciona melhor quando você enquadra explicitamente o pedido como uma tarefa de debugging e traz evidências. Exemplo:

“Use the debugger skill. This API returns 500 only in staging. Expected 200. Started after yesterday’s deploy. Here is the stack trace, the endpoint, and the last 3 commits.”

Esse prompt é muito mais forte do que “fix this bug.”

De que entrada a skill debugger precisa

Um bom uso da skill debugger depende de insumos concretos. Forneça o máximo possível destes itens:

• texto exato do erro
• stack trace
• comportamento esperado vs. comportamento real
• passos reproduzíveis
• mudanças recentes em código ou configuração
• detalhes do ambiente
• logs relevantes
• escopo já reduzido de arquivo ou componente

O fluxo da skill parte do princípio de que haverá coleta de evidências, então a falta de passos de reprodução ou de saída real afeta mais a qualidade do resultado do que a ausência de detalhes de implementação.

Como transformar um pedido vago em um bom prompt para debugger

Prompt fraco:
“Why does this fail?”

Prompt mais forte:
“Use the debugger skill to diagnose this failure. After upgrading dependencies, npm test fails in auth.spec.ts with TypeError: Cannot read properties of undefined. Expected tests to pass. Actual behavior: 6 failures on CI, 0 locally. Recent changes: lockfile update and config edit. Please help reproduce, isolate likely causes, rank hypotheses, and suggest the smallest safe fix.”

Por que isso funciona:

• define o objetivo de debugging
• informa comportamento esperado vs. real
• inclui divergência entre ambientes
• inclui mudanças recentes
• pede investigação antes de alterar o código

Fluxo de trabalho sugerido para debugger

Um guia debugger prático para uso real:

1. Reproduza o problema exatamente.
2. Registre o comportamento esperado vs. o comportamento real.
3. Verifique mudanças recentes com git log --oneline -10.
4. Colete logs ou traces.
5. Isole com um repro mínimo ou busca binária.
6. Relacione a falha a uma categoria de erro.
7. Formule hipóteses de causa raiz.
8. Teste a menor correção provável.
9. Valide com cobertura de regressão.

Isso é, em grande parte, o que a skill codifica, mas seguir esses passos explicitamente ajuda quando o agente começa a propor correções cedo demais.

Use os arquivos de referência como apoio de decisão

Os arquivos de apoio são curtos, mas mudam a qualidade da resposta:

• references/checklist.md mantém a sessão honesta: reproduzir, isolar, causa raiz, correção, cobertura de regressão.
• references/patterns.md é útil quando o problema é amplo ou ruidoso; sugere busca binária, logging direcionado e redução para repro mínimo.
• references/errors.md ajuda a classificar falhas comuns como acesso nulo, race conditions, incompatibilidades de configuração e desvio no formato dos dados.

Use esses arquivos quando a primeira saída da skill debugger parecer genérica. Eles são melhores para afinar o caminho da investigação do que para ensinar sintaxe.

Gere um relatório de debug reutilizável

Se você quiser um artefato documentado da investigação, use:

python skills/debugger/scripts/debug_report.py --name "Checkout timeout in staging" --owner payments

Isso cria um template de relatório em markdown com seções para resumo, ambiente, passos de reprodução, logs, causa raiz, correção, testes de regressão e próximos passos. Para depuração em equipe, esta é uma das partes mais práticas do repositório, porque transforma uma investigação passageira em algo revisável.

Melhores casos de uso da skill debugger para Debugging

Esta skill debugger é mais útil quando:

• o bug é reproduzível, mas não óbvio
• existem logs, mas com muito ruído
• a falha começou depois de uma mudança
• o problema atravessa código, configuração e ambiente
• você precisa de um fluxo disciplinado de triagem antes de editar código

Ela é menos convincente para erros minúsculos de sintaxe que você identifica na hora ou para incidentes muito específicos de domínio que exigem contexto operacional proprietário ao qual o agente não tem acesso.

Dicas práticas que melhoram o uso da skill debugger

Peça para a skill separar:

• fatos
• hipóteses
• próximas verificações
• correção proposta
• etapas de validação

Essa estrutura evita certeza prematura. Também vale pedir que ela ordene as causas mais prováveis e diga quais evidências refutariam cada uma. Isso transforma a skill debugger de “adivinhadora esperta” em uma parceira de investigação melhor.

FAQ da skill debugger

Esta skill debugger é melhor do que um prompt normal?

Em geral, sim, quando o problema tem várias etapas. Um prompt genérico costuma pular do sintoma para uma correção suposta. A skill debugger funciona melhor quando você precisa reduzir o escopo de forma sistemática, coletar evidências e validar o resultado. Se o bug for trivial e estiver totalmente visível em um único trecho, um prompt normal pode bastar.

A instalação da skill debugger é amigável para iniciantes?

Sim, porque o fluxo central é simples e concreto. Iniciantes se beneficiam do processo em fases e do checklist. O principal ponto de atenção é que a skill pressupõe que você consiga fornecer alguma evidência, como logs, stack traces ou passos de reprodução. Sem isso, qualquer guia debugger fica dependente demais de adivinhação.

Posso usar esta skill debugger com qualquer linguagem ou stack?

Na maior parte dos casos, sim. A skill debugger é orientada a processo, não presa a uma linguagem. Seus exemplos de erro são mais gerais do que específicos de framework. Isso a torna portátil, mas também significa que você talvez precise acrescentar detalhes específicos da sua stack para obter os melhores resultados.

Quando eu não devo usar esta skill debugger?

Evite usar quando:

• você precisa mais de debugging interativo em runtime do que de ajuda de raciocínio
• o problema é puramente operacional e o agente não consegue acessar o sistema
• o bug já foi identificado como um typo de uma linha
• você precisa de expertise específica de um fornecedor que o repositório não traz

Nesses casos, use primeiro as ferramentas diretas ou a documentação do domínio.

Ela ajuda em handoff de equipe e acompanhamento de incidente?

Sim. O script debug_report.py é o sinal mais forte de que esta skill debugger foi pensada para mais do que conversas pontuais. Ele ajuda a transformar uma sessão de depuração em um relatório reutilizável com responsável, passos de reprodução, causa raiz, correção e próximos passos.

Como melhorar a skill debugger

Dê evidências para a skill debugger, não apenas sintomas

A forma mais rápida de melhorar a saída da skill debugger é incluir evidências brutas:

• comando exato executado
• texto completo do erro
• entrada que falha
• ambiente em que quebra
• intervalo recente de commits
• o que você já tentou

“Here is the stack trace and the last good commit” é muito melhor do que “it’s broken after my changes.”

Force um repro mínimo logo no início

Um modo comum de falha no uso da skill debugger é investigar uma área ampla demais. Peça ajuda para criar o menor caso reproduzível possível. Isso costuma remover ruído de setup de framework, serviços não relacionados ou estado antigo e faz a causa raiz aparecer mais rápido.

Peça ranking de hipóteses

Quando várias causas são plausíveis, diga à skill debugger para classificá-las por probabilidade e por facilidade de verificação. Isso dá uma ordem melhor de investigação. Exemplo:

“List the top 3 root-cause hypotheses, what evidence supports each, and the next cheapest check to confirm or reject them.”

Isso é especialmente útil para testes flaky, falhas de integração e config drift.

Separe causa raiz da qualidade da correção

Outro problema comum é aceitar a primeira correção que faz o sintoma desaparecer. Use o guia debugger para perguntar:

• por que isso aconteceu
• que condição permitiu isso
• qual teste de regressão deve provar que continua corrigido

Isso importa para problemas recorrentes como tratamento de nulos, race conditions e configurações incompatíveis.

Melhore a primeira resposta com contexto do repositório

Se o bug estiver no seu próprio codebase, forneça:

• arquivos suspeitos
• fronteira do pacote ou serviço
• momento do deploy
• arquivos de configuração envolvidos
• se o problema acontece só localmente, em CI, em staging ou em produção

A skill debugger fica muito melhor quando consegue conectar evidências aos limites do sistema, em vez de raciocinar apenas a partir de um stack trace colado.

Use as referências para deixar respostas fracas mais precisas

Se a primeira resposta parecer genérica, diga explicitamente ao agente para usar:

• references/checklist.md para garantir completude do processo
• references/patterns.md para métodos de isolamento
• references/errors.md para correspondência com famílias de erro

Essa é uma forma prática de melhorar os resultados da skill debugger sem reescrever todo o prompt.

Itere após a primeira rodada de debugging

Um bom uso da skill debugger é iterativo. Depois da primeira resposta:

1. execute uma das verificações sugeridas
2. traga o resultado de volta
3. peça à skill que atualize as hipóteses
4. só então edite o código

É nesse loop que a skill debugger se torna mais útil do que um guia debugger estático. Ela ajuda você a convergir, em vez de gerar uma resposta única, longa e especulativa.

Adicione prova de regressão antes de encerrar

O checklist do repositório inclui explicitamente cobertura de regressão, e esse é o lugar certo para terminar. Peça à skill debugger que proponha o menor teste, assertion ou checagem de monitoramento capaz de detectar o problema na próxima vez. Uma correção sem verificação normalmente representa um Debugging incompleto, especialmente em casos intermitentes ou dependentes de ambiente.