| name | debug |
| description | Debugging sistemático para Fluig. Guia investigação de root cause em 4 fases: reproduzir, investigar, hipótese, corrigir com teste. Usa logs Docker, Playwright traces, Karma output. |
Você vai conduzir um debugging sistemático de erros encontrados em artefatos Fluig.
Fluxo de Debugging em 4 Fases
O debugging segue 4 fases obrigatórias em sequência. Não pule para "corrigir" sem antes completar reprodução, investigação e hipótese.
Fase 1 — Reproduzir o Erro
Passo 1a — Obter descrição exata do erro
Pergunte ao usuário:
- Qual é o erro exato observado? (mensagem, comportamento inesperado, falha silenciosa)
- Em qual cenário ocorre? (ao carregar formulário, ao submeter dados, ao filtrar dataset)
- É reproduzível consistentemente ou intermitente?
- Em qual ambiente? (localhost, servidor HML, servidor de teste)
Passo 1b — Reproduzir localmente ou no servidor
Se é erro em localhost (Karma, servidor local):
npm test
npm start
Verifique:
- Console do navegador (F12) — há erros JavaScript?
- Output do Karma — qual teste falhou e com que mensagem?
Se é erro no servidor deployado (HML ou teste):
ssh [hostname] "docker logs fluig --tail 100 2>&1"
Procure por:
- Stack trace no stdout
- Exceções Java (se Fluig logging capturar)
- Timing de quando o erro ocorreu
Passo 1c — Coletar evidências do erro
- Captura de tela ou vídeo do comportamento (se no navegador)
- Stack trace completo (copie do console ou dos logs)
- Playground trace do Playwright (se teste E2E falhou) — verifique
test-results/ ou playwright/traces/
- Versão do artefato, servidor e ambiente
Fase 2 — Investigar
Passo 2a — Coletar logs relevantes
Logs Docker (servidor Fluig):
ssh [hostname] "docker logs fluig --since 10m 2>&1 | tail -200"
Procure por:
- Timestamp próximo ao momento do erro
- Linhas com
ERROR, WARN, Exception
- Stack traces Java completos
Logs do Karma (localhost):
npm test 2>&1 | tee test.log
Playwright traces:
ls -la test-results/
npx playwright show-trace test-results/*.trace
Passo 2b — Revisar mudanças recentes
git diff HEAD~5..HEAD [arquivo do artefato]
git log -p --follow [arquivo] | head -100
Identifique:
- Qual mudança foi feita antes do erro aparecer?
- Ela poderia ter causado o comportamento observado?
Passo 2c — Verificar dependências e variáveis de ambiente
Se é erro de integração com Protheus:
- URL da API está correta no CLAUDE.md?
- Token/credenciais estão válidas?
- Protheus está acessível (não down)?
Se é erro de dataset:
- A query SQL/JPQL está correta?
- Os parâmetros de entrada estão sendo validados?
- O banco de dados retorna resultado vazio (edge case)?
Se é erro de widget Angular:
- Dependências npm estão instaladas (
npm list @po-ui/core, etc.)?
- Versão do @po-ui está compatível?
Fase 3 — Hipótese
Passo 3a — Formar hipótese baseada em evidências
Liste 2-3 possíveis causas ordenadas por probabilidade:
Hipótese 1 (provável): [descrição]
Evidência: [qual log ou comportamento suporta isso]
Como validar: [qual comando ou teste valida]
Hipótese 2 (possível): [descrição]
Evidência: [qual evidência]
Como validar: [qual teste]
Hipótese 3 (improvável): [descrição]
Evidência: [qual evidência]
Como validar: [qual teste]
Passo 3b — Validar contra evidências
Para cada hipótese:
- Ela explica TODOS os sintomas observados?
- Há contradições com os logs ou comportamento?
- Qual hipótese é mais consistente com as evidências?
Descarte hipóteses que contradigem evidências.
Fase 4 — Corrigir com Teste
Passo 4a — Escrever teste que reproduz o bug PRIMEIRO
Antes de corrigir o código, escreva um teste que falhe:
Para templates de correção, consulte o MCP:
searchFluigPatterns({ category: "template" })
searchFluigPatterns({ category: "error-handling" })
Aplique o padrão correto ao tipo de artefato sendo debugado.
Execute o teste e confirme que falha:
npm test 2>&1 | grep FAIL
Passo 4b — Corrigir o código
Com o teste falhando, agora corrija o artefato usando os padrões obtidos do MCP.
Passo 4c — Validar: teste passa, bug não ocorre mais
npm test -- --include='**/nome.spec.ts'
npm start
Se no servidor:
/fluig:deploy
/fluig:test
Confirme:
- ✅ Teste unitário passa
- ✅ Comportamento no navegador/servidor é correto
- ✅ Nenhuma regressão em outros testes
Fontes de Debugging Fluig
Docker logs (servidor):
ssh [hostname] "docker logs fluig --tail 50 --timestamps"
Playwright traces (E2E):
ls -la test-results/
npx playwright show-trace test-results/*.trace
Karma output (localhost):
npm test 2>&1 | grep -A 20 "FAIL"
Browser console (F12):
- Abra DevTools (F12)
- Network tab — verifique requisições à API/Protheus
- Console tab — erros JavaScript
- Application tab — localStorage/cookies se relevante
Resumo Final
Após corrigir e validar, anuncie:
BUG CORRIGIDO — [descrição do bug]
Root cause: [hipótese confirmada]
Correção: [mudança de código aplicada]
Teste: [teste unitário que valida a correção]
Validação: [comportamento correto confirmado]
Próximo passo: Retorne para /fluig:deploy → /fluig:qa para validar a correção em toda a pipeline.
Regras obrigatórias
- As 4 fases são sequenciais — não pule reprodução ou investigação
- Sempre escrever teste ANTES de corrigir (TDD)
- Sempre validar que o teste passa após correção
- Sempre coletar logs (Docker, Playwright, Karma) antes de especular
- Fase 3 (hipótese) é teórica — validar com testes ou logs, nunca assumir
Consulta de Conhecimento
Se precisar de informação não disponível no MCP, consulte o RAG:
searchKnowledge({ keyword: "<termo relevante>" })
