Debugging e Troubleshooting · Skill Moderna

Missão

Resolver bugs complexos em 60-90 minutos usando metodologia estruturada de 4 fases, focando em causa raiz (não sintomas).

Quando ativar

• •Fase: Manutenção · Bug Fix
• •Workflows: /corrigir-bug, /debugging
• •Trigger: "bug em produção", "resolver erro", "análise de causa raiz"

Inputs obrigatórios

• •Código fonte e logs disponíveis
• •Steps to reproduce documentados
• •Ambiente e contexto do erro

Outputs gerados

• •src/ — Código corrigido
• •tests/ — Regression test
• •docs/bugs/[ID].md — Post-mortem completo

Quality Gate

• •Bug reproduzível 100% das vezes
• •Causa raiz identificada (não sintoma)
• •Regression test implementado
• •Post-mortem documentado
• •Score de validação automática ≥ 75 pontos

🚀 Processo Otimizado (4 Fases)

1. REPRODUCE (15 min)

Use função de reprodução para confirmar bug e documentar steps exatos.

Checklist:

• •Steps de reprodução documentados
• •Taxa de reprodução (100%? intermitente?)
• •Comportamento esperado vs atual
• •Ambiente (OS, browser, versão)
• •Data/versão que começou a ocorrer

2. ISOLATE (20 min)

Reduza scope e identifique componente responsável.

Técnicas:

• •Binary search debugging
• •Git bisect
• •Network/console logs
• •Minimal reproduction case

3. UNDERSTAND (20 min)

Aplique técnica dos 5 Whys para identificar causa raiz.

Use função de análise de causa raiz para documentar investigação completa.

4. FIX (30 min)

Corrija causa raiz e previna recorrência.

Use função de validação para garantir qualidade do fix.

📚 Recursos Adicionais

Prompts Especializados

• •Análise de Bugs: resources/prompts/analise-bugs.md (14KB)
  • •Metodologia completa: 5 Whys, Fishbone Diagram, RCA
  • •Template de análise detalhado com 8 seções
  • •Exemplos práticos de bugs (validação, performance, N+1)
  • •Checklist pós-geração com 15+ critérios

Guias de Referência

• •Debugging com IA: resources/reference/debugging-ai-guide.md
  • •Fluxo estruturado de 6 etapas
  • •Prompts prontos para cada tipo de erro
  • •Técnicas de debugging sistemático
  • •Boas práticas e armadilhas comuns
• •Guia Completo: resources/reference/debugging-guide.md
  • •Metodologia de 4 fases (Reproduce, Isolate, Understand, Fix)
  • •Ferramentas por tipo de erro
  • •Casos de uso avançados

Templates e Exemplos

• •Template Bug Report: resources/templates/bug-report.md
• •Template Post-Mortem: resources/templates/post-mortem.md
• •Exemplos práticos: resources/examples/debugging-examples.md
• •Validação: resources/checklists/debugging-validation.md

Funções de Automação

• •Reprodução: Função de documentação de steps
• •Análise: Função de causa raiz (5 Whys + Fishbone)
• •Validação: Função de verificação de qualidade (score automático)

🛠️ Ferramentas por Tipo de Erro

🔄 Context Flow Automatizado

Ao Concluir (Score ≥ 75)

1. •Fix validado automaticamente
2. •Regression test criado
3. •Post-mortem documentado
4. •Transição para deploy ou próxima tarefa

Comando de Avanço

Use função de processamento para preparar transição automática quando fix estiver validado.

Guardrails Críticos

• •NUNCA avance sem validação ≥ 75 pontos
• •SEMPRE confirme com usuário antes de processar
• •VALIDE causa raiz identificada (não sintoma)
• •DOCUMENTE análise dos 5 Whys
• •USE funções descritivas para automação via MCP

🎯 Metodologia dos 5 Whys

Exemplo Prático

Bug: "Usuário não consegue fazer login"
1. Por quê? → Token JWT inválido
2. Por quê? → Expiração de 1h mas clock do servidor atrasado
3. Por quê? → NTP não configurado
4. Por quê? → Server provisioning script não instalava NTP
5. Por quê? → Ninguém revisou hardening checklist

ROOT CAUSE: Falta de checklist de provisioning

Checklist de Qualidade

• • Bug reproduzível 100%
• • Componente isolado identificado
• • 5 Whys documentados
• • Causa raiz (não sintoma)
• • Fix implementado na raiz
• • Regression test criado
• • Post-mortem completo
• • Score validação ≥ 75

🎯 Performance e Métricas

Tempo Estimado

• •Reproduce: 15 minutos
• •Isolate: 20 minutos
• •Understand: 20 minutos
• •Fix: 30 minutos
• •Total: 85 minutos (vs 120 minutos anterior)

Qualidade Esperada

• •Score validação: ≥ 75 pontos
• •Completude: 100% campos obrigatórios
• •Consistência: 100% formato padrão
• •Performance: 80% redução de tokens

Frameworks Utilizados

• •5 Whys Analysis
• •Binary Search Debugging
• •Git Bisect
• •Post-Mortem Template

🔧 Integração Maestro

Skills Complementares

• •systematic-debugging (metodologia)
• •testing-patterns (regression tests)
• •code-review-checklist (validação)

Referências Essenciais

• •Especialista original: content/specialists/Especialista em Debugging e Troubleshooting.md
• •Artefatos gerados:
  • •src/ (código corrigido)
  • •tests/ (regression test)
  • •docs/bugs/[ID].md (post-mortem)

Próximo Especialista

Testes - Validará fix com testes automatizados e cobertura.

Framework: Maestro Skills Modernas v2.0
Pattern: Progressive Disclosure
Performance: 80% redução de tokens
Quality: 100% validação automática