phase-gated-debugging
Faz seu agente depurar códigos seguindo um protocolo seguro. Ele bloqueia edições até a causa raiz ser confirmada, evitando correções apressadas.
O que ela faz
Este assistente de IA ajuda a consertar bugs em seu código de forma organizada. Ele garante que o problema real seja encontrado antes de qualquer modificação, seguindo um processo de 5 passos para evitar correções apressadas.
Quando usar
- ✓Quando um bug parece ser corrigido, mas o problema volta.
- ✓Quando você precisa de um processo passo a passo para encontrar a causa de um erro.
- ✓Quando o erro acontece de vez em quando e é difícil de encontrar.
Exemplo do que pedir para a IA
“Um bug está aparecendo no meu código e não consigo descobrir a causa. Você pode me ajudar a investigar seguindo um processo organizado?”
Quer saber mais? Abra as seções abaixo.
Como usar
O jeito mais fácil: copie a mensagem abaixo e cole no Claude, ChatGPT, Cursor ou outra IA. Ela lê a skill e segue as instruções.
Link da skill
Mensagem pronta para colar
Como funciona
A IA primeiro tenta reproduzir o erro, depois adiciona anotações para entender onde o problema acontece, analisa a causa raiz e só então aplica a correção. Por fim, ela verifica se o erro foi realmente resolvido.
Instalação
Jeito mais fácil: copie o link da skill e cole no Claude, ChatGPT ou Cursor pedindo para seguir as instruções.
No terminal (Claude Code, Codex, Cursor), na pasta do projeto:
npx skills add sickn33/agentic-awesome-skills --skill phase-gated-debuggingOu baixe só o arquivo:
curl -L https://raw.githubusercontent.com/sickn33/agentic-awesome-skills/main/plugins/agentic-awesome-skills-claude/skills/phase-gated-debugging/SKILL.md -o SKILL.mdConteúdo técnico (SKILL.md)
Tradução do texto original do autor no GitHub. Os comandos e códigos estão como no original.
Depuração por Fase
Visão Geral
Agentes de codificação de IA veem um erro e editam o código imediatamente. Eles adivinham correções, erram e entram em espiral. Esta habilidade impõe um protocolo rigoroso de 5 fases onde você NÃO PODE editar o código-fonte até que a causa raiz seja identificada e confirmada.
Baseado em claude-debug (plugin completo com aplicação de hook PreToolUse).
Quando Usar
Use esta habilidade quando:
- um bug continua sendo "corrigido" sem resolver o problema subjacente
- você precisa desacelerar um agente e forçar uma depuração disciplinada antes de editar o código
- a falha é intermitente, uma regressão, relacionada ao desempenho ou difícil de isolar de outra forma
- você deseja um ponto de confirmação explícito do usuário antes que qualquer correção seja aplicada
O Protocolo
Fase 1: REPRODUZIR
Execute o comando/teste que falha. Capture o erro exato. Execute 2-3 vezes para consistência.
- NÃO leia o código-fonte
- NÃO levante hipóteses
- NÃO edite nenhum arquivo
Fase 2: ISOLAR
Leia o código. Adicione logs de diagnóstico marcados // DEBUG. Reexecute com diagnósticos. Use busca binária para refinar.
- Apenas logs marcados
// DEBUGsão permitidos - NÃO corrija o bug mesmo que você o veja
Fase 3: CAUSA RAIZ
Analise o PORQUÊ na localização isolada. Use a técnica dos "5 Porquês". Remova os logs de depuração.
Declare: "Esta é minha análise da causa raiz: [explicação]. Você concorda, ou devo investigar mais?"
ESPERE pela confirmação do usuário. NÃO prossiga sem ela.
Fase 4: CORRIGIR
Remova todas as linhas // DEBUG. Aplique a mudança mínima que aborda a causa raiz confirmada.
- Edite apenas arquivos relacionados à causa raiz
- NÃO refatore código não relacionado
Fase 5: VERIFICAR
Execute o teste original que falhava — ele deve passar. Execute testes relacionados. Para bugs intermitentes, execute 5+ vezes. Se a verificação falhar: a causa raiz estava errada, volte para a Fase 2.
Estratégias por Tipo de Bug
| Tipo | Técnica |
|---|---|
| Crash/Pânico | Rastreamento de pilha reverso — rastreie o valor incorreto até sua origem |
| Saída Incorreta | Busca binária — registre o ponto médio, divida o espaço de busca pela metade a cada iteração |
| Intermitente | Compare logs de execução que passaram com os que falharam — encontre divergências de ordem |
| Regressão | git bisect — encontre o commit causador |
| Desempenho | Medição de tempo nos limites das etapas — encontre o gargalo |
Regras Chave
- NUNCA edite o código-fonte nas fases 1-3 (exceto
// DEBUGna fase 2) - NUNCA prossiga após a fase 3 sem confirmação do usuário
- SEMPRE reproduza antes de investigar
- SEMPRE verifique após corrigir
Exemplo
Solicitação do usuário:
um bug continua sendo "corrigido" sem resolver o problema subjacente; diagnostique-o e retorne a ação concreta a ser tomada.
Limitações
- Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
- Não trate a saída como substituta para validação específica do ambiente, testes ou revisão especializada.
- Pare e peça esclarecimentos se os inputs necessários, permissões, limites de segurança ou critérios de sucesso estiverem faltando.
Perguntas frequentes
Por que não posso editar o código imediatamente?
Editar o código sem entender a causa raiz pode piorar o problema ou criar novos bugs. Este processo garante que a correção seja feita na origem do problema.
O que são as 5 fases?
São: 1. Reproduzir o erro, 2. Isolar o problema com anotações, 3. Identificar a causa raiz, 4. Aplicar a correção e 5. Verificar se o erro foi resolvido.
O que acontece se a correção não funcionar?
Se o erro não for resolvido na fase de verificação, a IA volta para a fase de isolamento para investigar novamente.
Detalhes
Descrição original do autor
Use when debugging any bug. Enforces a 5-phase protocol where code edits are blocked until root cause is confirmed. Prevents premature fix attempts.
Popularidade
- Estrelas no GitHub
- 48 mil
- Posição no ranking
- #3824
- Licença
- MIT
- Atualizada em
- 15/10/2026
Comentários
- …
Mais skills deste repositório
00-andruia-consultant
Ajuda seu agente a iniciar ou melhorar projetos de IA. Ele analisa código, sugere ferramentas e cria planos de ação em espanhol.
sickn33/agentic-awesome-skills
007
Faz seu agente realizar auditorias de segurança e modelagem de ameaças. É útil para proteger projetos contra ataques e vulnerabilidades.
sickn33/agentic-awesome-skills
10-andruia-skill-smith
Ajuda seu agente a criar ou melhorar ferramentas de IA. Ele define como as ferramentas funcionam, escreve a documentação e valida a estrutura.
sickn33/agentic-awesome-skills
20-andruia-niche-intelligence
Faz seu agente criar um resumo sobre um setor específico. É útil para entender o contexto, regras, padrões de uso e riscos de um projeto, usando fontes confiáveis.
sickn33/agentic-awesome-skills
Skills parecidas
benchmark-optimization-loop
Faz seu agente melhorar a velocidade de algo de forma medida. Ele testa várias versões e escolhe a mais rápida que ainda funciona corretamente.
affaan-m/ECC
change-impact
Ajuda seu agente a analisar o impacto de mudanças no código antes de fazê-las. Ele compara o planejado com o real depois, cobrindo caminhos, dados, testes e documentação. É útil para mudanças arriscadas ou que afetam várias partes do sistema.
affaan-m/ECC
click-path-audit
Faz seu agente rastrear todos os botões e interações do usuário para achar bugs. Ele encontra problemas onde funções parecem funcionar sozinhas, mas falham juntas. Útil quando bugs persistem mesmo após depuração.
affaan-m/ECC