95 lines
4.0 KiB
Markdown
95 lines
4.0 KiB
Markdown
---
|
|
name: resolving-problems
|
|
description: A universal framework for diagnosing and resolving technical problems (bugs, errors, failures) in any application. Use when the user presents a generic error or bug.
|
|
---
|
|
|
|
# Objetivo
|
|
|
|
Fornecer um roteiro estruturado para investigar, diagnosticar e corrigir problemas de forma eficiente, evitando "tentativa e erro" aleatória. Esta skill deve ser usada sempre que o usuário apresentar um erro genérico, um bug, ou uma falha inesperada.
|
|
|
|
# 1. Definição e Entendimento
|
|
|
|
Antes de qualquer alteração de código, é crucial entender o cenário.
|
|
|
|
**Perguntas Chave:**
|
|
|
|
1. **O que está acontecendo?** (Descreva o sintoma exato, mensagem de erro).
|
|
2. **O que deveria acontecer?** (Comportamento esperado).
|
|
3. **Qual o impacto?** (Crítico, bloqueante, visual, cosmético).
|
|
4. **Onde ocorre?** (Ambiente local, produção, URL específica, componente específico).
|
|
|
|
# 2. Reprodução
|
|
|
|
Se você não consegue reproduzir, você não consegue consertar (ou verificar a correção).
|
|
|
|
**Ações:**
|
|
|
|
- **Identifique os passos:** Crie um roteiro passo-a-passo (A -> B -> C) que causa o erro consistentemente.
|
|
- **Logs em Tempo Real:** Abra os logs (`tail -f log/development.log`, logs do container, console do navegador) _enquanto_ executa a reprodução.
|
|
- **Isolamento de Variáveis:** O erro persiste se trocar o navegador? Se trocar o usuário?
|
|
|
|
# 3. Diagnóstico e Isolamento
|
|
|
|
Reduza o escopo para encontrar a raiz do problema.
|
|
|
|
**Estratégia de Divisão (Divide and Conquer):**
|
|
|
|
- **Frontend vs Backend:**
|
|
|
|
- Verifique a aba **Network** do navegador.
|
|
- Se a requisição falha (500, 404), o problema provável é no **Backend**.
|
|
- Se a requisição retorna sucesso (200) mas a tela quebra ou mostra dados errados, o problema provável é no **Frontend**.
|
|
- Se nem há requisição, o erro é no JS do **Frontend** antes do envio.
|
|
|
|
- **Stack Trace Analysis:**
|
|
- **NUNCA ignore o Stack Trace.** Leia a primeira linha que aponta para _o código da aplicação_ (ignore linhas de bibliotecas/gems inicialmente).
|
|
- Identifique a Exception exata e a linha do arquivo.
|
|
|
|
# 4. Ferramentas de Investigação
|
|
|
|
Use as ferramentas disponíveis no ambiente.
|
|
|
|
- **Pesquisa no Código (Grep/Search):** Procure pela mensagem de erro ou pelo código do erro para achar onde ele é disparado.
|
|
- **Debugger:**
|
|
- **Ruby:** Adicione `binding.pry` antes da linha suspeita.
|
|
- **JS:** Adicione `debugger;` ou `console.log` antes da linha suspeita.
|
|
- **Database:** Verifique se os dados no banco correspondem ao esperado (`Rails Console`, `psql`).
|
|
|
|
# 5. Aplicação da Solução
|
|
|
|
Ao identificar a causa raiz, planeje a correção.
|
|
|
|
**Princípios:**
|
|
|
|
- **Corrija a Causa, não o Sintoma:** Se uma variável é nula, entenda _por que_ ela é nula, não apenas coloque um `if variable`.
|
|
- **Mudança Mínima:** Evite refatorar código não relacionado ao bug enquanto corrige o bug.
|
|
- **Defensividade:** Adicione tratamentos de erro adequados se o erro for causado por inputs externos imprevisíveis.
|
|
|
|
# 6. Verificação e Documentação
|
|
|
|
Garanta que o problema sumiu e não voltará.
|
|
|
|
**Passos:**
|
|
|
|
1. **Teste a Reprodução:** Execute os passos da etapa 2 novamente. O erro deve ter desaparecido.
|
|
2. **Teste Casos de Borda:** Teste variações (input vazio, input inválido).
|
|
3. **Documentação:** Se o problema foi complexo, crie uma nota em `/progresso` explicando o problema e a solução para referência futura.
|
|
|
|
# Dicas Específicas por Tecnologia
|
|
|
|
## Ruby on Rails
|
|
|
|
- **Erro de Rota?** Rode `rails routes | grep termo`.
|
|
- **Erro de DB?** Verifique `schema.rb` e migrations.
|
|
- **Console:** Use `rails c` para instanciar modelos e chamar métodos diretamente, isolando a camada HTTP.
|
|
|
|
## Vue.js / Frontend
|
|
|
|
- **Vue DevTools:** Inspecione a hierarquia de componentes. O componente recebeu as `props` certas? O `data` está correto?
|
|
- **Console:** Se o erro é "undefined is not a function", verifique imports e tipos.
|
|
|
|
## Infraestrutura
|
|
|
|
- **Serviços Rodando?** Verifique se Redis, Postgres, Sidekiq estão rodando (`docker ps`, `ps aux`).
|
|
- **Variáveis de Ambiente:** Verifique `.env`.
|