systematic-debugging

Files (1)

• SKILL.md

SKILL.md (first lines)

# Systematic Debugging Skill

## Metodologia: 5 Passos Antes de Tocar no Código

```
1. OBSERVAR   → Ler o erro completo, sem pular linhas
2. ISOLAR     → Reduzir ao mínimo reproduzível
3. HIPÓTESE   → Formular causa provável (1 por vez)
4. VERIFICAR  → Confirmar hipótese com log/teste, não com palpite
5. CORRIGIR   → Só então modificar código
```

**Nunca pule para o passo 5 sem completar os anteriores.**

---

## Análise de Logs de Erro

### Onde buscar logs neste projeto

| Fonte | Endpoint / Comando |
|---|---|
| Logs Playwright (SSE) | `GET /api/executar/{sessao_id}` — saída em tempo real |
| Logs Python webapp | `GET /api/logs/python` — últimas 300 linhas do logger |
| Logs Java / Tomcat | `GET /api/logs/java` e `GET /api/logs/tomcat` |
| Screenshot Xvfb | `GET /api/screenshot` |
| Processos ativos | `GET /api/ps` |
| Tomcat disponível | `GET /api/verificar_pjecalc` |

### Leitura de traceback Python

```
Sempre ler de baixo para cima:
  linha mais baixa  = erro imediato (o que explodiu)
  linhas do meio    = call stack (quem chamou o quê)
  linha mais alta   = onde o fluxo entrou
```

### Palavras-chave críticas neste projeto

| Mensagem | Diagnóstico |
|---|---|
| `Execution context was destroyed` | Página ainda navegando quando `evaluate()` foi chamado |
| `Target page, context or browser has been closed` | Browser crashou — `fechar()` foi chamado sem restart |
| `Playwright Sync API inside the asyncio loop` | Thread não tem loop próprio — `asyncio.set_event_loop(new_event_loop())` |
| `ViewExpiredException` / `ViewExpired` | JSF ViewState expirou — recarregar página |
| `503 Service Unavailable` | Proxy timeout: Python demorou >30s ou unhandled exception |
| `HTTP 500` no PJE-Calc | AJAX postback JSF falhou — geralmente blur disparado antes da hora |
| `networkidle timeout` | PJE-Calc travado em AJAX pendente |
| `StaleElementReferenceException` | DOM foi re-renderizado pelo RichFaces após AJAX |

---

## Reprodução Mínima

### Princípio
> O menor código que exibe o bug é o mais fácil de corrigir.

### Checklist de isolamento

- [ ] Bug ocorre com dados específicos ou com qualquer dado?
- [ ] Bug ocorre só na primeira execução ou em todas?
- [ ] Bug ocorre só em Railway/Docker ou também localmente?
- [ ] Bug ocorre em headless ou também em modo visível?
- [ ] Qual fase do Playwright falha? (1=dados, 2=histórico, 3=verbas…)
- [ ] O browser abre e carrega o PJE-Calc antes do erro?

### Reproduzir em isolamento (módulo playwright)

```python
# Testar fase específica sem rodar o pipeline completo
from modules.playwright_pjecalc import PJECalcPlaywright

agente = PJECalcPlaywright(log_cb=print)
agente.iniciar_browser(headless=False)  # visível para diagnóstico
# navegue manualmente até onde quer testar, então:
agente.fase_verbas(verbas_mapeadas_teste)
agente.fechar()
```

---

## Debugging de Race Conditions

Race conditions mais comuns neste projeto:

### 1. Navegação JSF ainda em progresso

**Sintoma:** `Execution context was destroyed`
**Causa:** `evaluate()` chamado enquanto JSF faz redirect/partial update
**Fix:**
```python
# Antes de qualquer evaluate() após navegação:
try:
    page.wait_for_load_state("networkidle", timeout=10000)
except Exception:
    page.wait_for_timeout(2000)
self._aguardar_ajax()
```

### 2. AJAX RichFaces não completou

**Sintoma:** Campos aparecem preenchidos na tela mas não são salvos
**Causa:** `blur` disparado prematuramente aciona postback AJAX que recarrega o campo
**Fix:**
```python
# NÃO usar .press("Tab") após fill() em campos JSF
# NÃO usar .dispatch_event("blur")
# Usar apenas:
loc.fill(valor)
loc.dispatch_event("input")
loc.dispatch_event("change")
# Depois aguardar AJAX antes de interagir com próximo campo
```

### 3. Thread asyncio vs sync_playwright

**Sintoma:** `Playwright Sync API inside the asyncio loop`
**Causa:** Thread herdou referência ao loop do uvicorn

From bragabarreto/pjecalc-agente, MIT.

More from bragabarreto/pjecalc-agente