# Ag Depurar Erro

> Diagnostica e corrige bugs. Le errors-log.md antes de comecar para nao repetir tentativas que ja falharam. Use quando algo nao funciona, da erro, quebrou, trava, build falha, ou qualquer comportamento inesperado.

- **Type:** Skill
- **Install:** `agentstack add skill-andregusman-raiz-a-gusman-claude-ag-depurar-erro`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [andregusman-raiz](https://agentstack.voostack.com/s/andregusman-raiz)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [andregusman-raiz](https://github.com/andregusman-raiz)
- **Source:** https://github.com/andregusman-raiz/a-gusman-claude/tree/main/skills/ag-depurar-erro

## Install

```sh
agentstack add skill-andregusman-raiz-a-gusman-claude-ag-depurar-erro
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ag-depurar-erro — Depurar Erro

> **Reasoning protocol (Opus-only, equivalente a `reasoning_effort=xhigh` do Codex)**: ANTES de propor diagnostico, Exhaust 3+ hipoteses concorrentes → Verify cada uma com Read/Bash/grep → Falsify (o que refutaria?) → Connect cadeia causal sintoma→causa→fix → Report com confianca explicita (alta/media/baixa). Detalhes: `.claude/rules/deep-reasoning-directive.md`. NUNCA aceitar primeira hipotese plausivel sem listar concorrentes.

Spawn the `ag-depurar-erro` agent to diagnose and fix bugs using root cause analysis.

## Invocation

Use the **Agent tool** with:
- `subagent_type`: `ag-depurar-erro`
- `mode`: `bypassPermissions`
- `run_in_background`: `true`
- `prompt`: Compose from template below + $ARGUMENTS

## Dynamic Context
- **Errors known**: !`head -30 docs/ai-state/errors-log.md 2>/dev/null || echo "none"`

## Prompt Template

```
Projeto: [CWD or user-provided path]
Erro: [error message or description from $ARGUMENTS]
Contexto: [when it happens, what changed, environment]

Fluxo: Reproduzir → Isolar → Diagnosticar → Corrigir → Verificar.
- Ler errors-log.md ANTES de comecar (nao repetir tentativas falhadas)
- Encontrar causa raiz, NAO apenas sintoma
- Verificar SEMPRE se existem multiplas causas independentes
- Max 2 tentativas de fix por causa — escalar ao usuario se nao resolver
- Registrar diagnostico e resolucao em errors-log.md
```

## Important
- ALWAYS spawn as Agent subagent — do NOT execute inline
- After spawning, confirm to the user that the debug agent is running
- Reads errors-log.md to avoid repeating failed attempts
- Follows root-cause-debugging.md protocol

## Decision Tree: Classifying the Bug

```
BUG REPORTADO
├── Fix aplicado mas bug persiste? → DEPLOY GAP
│   ├── Verificar: build atual reflete o codigo?
│   ├── Verificar: cache (CDN, browser, server) invalidado?
│   ├── Verificar: processo reiniciado apos deploy?
│   └── Verificar: deploy foi para o ambiente correto (prod vs staging)?
│
├── Bug aparece em camadas diferentes? → MULTI-LAYER BUG
│   ├── Frontend: componente renderiza dado errado?
│   ├── Backend: API retorna valor incorreto?
│   ├── Config: variavel de ambiente ausente ou errada?
│   └── → Rastrear da UI ate banco — corrigir TODAS as camadas
│
├── Funciona para alguns users mas nao outros? → PERMISSION/ACL BUG
│   ├── RLS policy inconsistente entre tabelas relacionadas?
│   ├── Role/claim ausente no JWT?
│   ├── Middleware valida permissao diferente da query?
│   └── → Auditar toda a cadeia: JWT → middleware → RLS → query
│
└── Bug unico e isolado? → SINGLE-CAUSE BUG
    └── Fluxo padrao: Reproduzir → Root Cause → Fix → Verificar
```

## Multi-Cause Investigation Protocol

Apos corrigir a primeira causa raiz, SEMPRE executar:

```
1. O fix eliminou completamente o erro ou apenas reduziu?
   → Se apenas reduziu: existe causa adicional independente

2. Mapear todos os caminhos de codigo que poderiam produzir o mesmo sintoma:
   - Caminho A: [causa 1] → verificar se foi corrigido
   - Caminho B: [causa 2] → verificar se existe
   - Caminho C: [causa 3] → verificar se existe

3. Para cada causa identificada:
   - Corrigir independentemente
   - Verificar individualmente
   - Documentar no errors-log.md como causa separada

4. Fix considerado completo SOMENTE quando:
   - Cenario original nao reproduz mais
   - Variacoes do cenario tambem nao reproduzem
   - Nenhum caminho alternativo para o bug existe
```

## Deploy Gap Checklist

Quando fix foi aplicado mas bug ainda aparece em producao:

```
[ ] git log --oneline -5  → commit do fix esta no historico?
[ ] CI/CD pipeline → build passou? deploy completou?
[ ] curl -I  → headers mostram versao/timestamp atualizado?
[ ] Hard refresh (Ctrl+Shift+R) → elimina cache do browser?
[ ] CDN purge necessario? (Vercel: automatic, outros: manual)
[ ] Server-side cache? (Redis, in-memory) → invalidar ou reiniciar
[ ] Environment correto? (VERCEL_ENV, NODE_ENV, APP_ENV)
[ ] Feature flag desabilitando o fix em prod?
[ ] Multiple replicas? → rolling deploy pode manter versao antiga por minutos
```

## Multi-Layer Bug: Rastreamento Completo

Para bugs que envolvem frontend + backend + config:

```
CAMADA UI
└── O componente recebe o dado correto?
    └── Console.log / React DevTools → qual valor chega?

CAMADA API/SERVICE
└── O endpoint retorna o valor correto?
    └── curl / Postman → testar endpoint diretamente

CAMADA NEGOCIO
└── A logica de negocio processa o dado corretamente?
    └── Unit test isolado → confirmar comportamento esperado

CAMADA DADOS
└── O banco retorna o dado correto?
    └── Query direta no banco → confirmar dados em storage

CAMADA CONFIG
└── Variaveis de ambiente corretas?
    └── printenv | grep  → confirmar valores reais vs esperados

REGRA: Fix incompleto se qualquer camada ainda propaga o erro.
       Documentar cada camada no errors-log.md separadamente.
```

## Permission/ACL Inconsistency Protocol

Para bugs de permissao que afetam apenas alguns usuarios/roles:

```
1. IDENTIFICAR o escopo:
   - Afeta role especifica? (admin, user, guest)
   - Afeta recurso especifico? (tabela, rota, componente)
   - Afeta operacao especifica? (read, write, delete)

2. AUDITAR a cadeia completa:
   JWT/Session → Middleware → Route Guard → API → RLS Policy → Query

3. VERIFICAR consistencia entre camadas:
   - Middleware permite role X? → RLS tambem permite role X?
   - Frontend esconde botao para role Y? → Backend tambem bloqueia para role Y?
   - NUNCA confiar apenas em UI para seguranca

4. TESTAR com usuario real de cada role afetada:
   - Criar token/session com role especifica
   - Executar operacao que falha
   - Confirmar fix para cada role

5. EXEMPLOS de inconsistencias comuns:
   - RLS policy usa auth.uid() mas middleware verifica user_id diferente
   - Role 'editor' tem RLS mas nao tem claim no JWT
   - Tabela A tem RLS correto, tabela B relacionada nao tem
   - Middleware novo adicionado sem atualizar RLS correspondente
```

## Escalacao: Issue para Problemas Nao Resolvidos

Apos esgotar 2 tentativas de fix sem sucesso, ALEM de escalar ao usuario:

1. Spawnar ag-registrar-issue para registrar GitHub Issue com contexto completo:
```
Agent({
  subagent_type: "ag-registrar-issue",
  name: "issue-registrar",
  model: "haiku",
  run_in_background: true,
  prompt: "Repo: [detectar via git remote]\nOrigem: ag-depurar-erro\nSeveridade: [P0 se prod, P1 se dev]\nTitulo: [descricao concisa do bug]\nContexto: [erro completo + 2 tentativas de fix + por que falharam]\nArquivos: [arquivos investigados]\nLabels: bug"
})
```
2. Isso garante que o problema nao se perde mesmo se o usuario nao agir imediatamente.

## Output
- Bug(s) corrigido(s) com TODAS as causas raiz documentadas
- docs/ai-state/errors-log.md atualizado (sintoma, causas, tentativas, solucao)
- Deploy verificado: versao com fix ativa em producao
- Teste de regressao sugerido ou criado via ag-testar-codigo
- **Se nao resolvido**: GitHub Issue criada via ag-registrar-issue com todo o contexto

## Anti-Patterns
- NUNCA parar na primeira causa — investigar se existem causas independentes adicionais
- NUNCA ignorar Deploy Gap — se bug persiste apos fix, SEMPRE verificar se deploy esta ativo
- NUNCA corrigir sem reproduzir — fix sem reproducao e chute
- NUNCA repetir tentativa que ja falhou — ler errors-log.md ANTES
- NUNCA usar `as any` ou try/catch generico como "fix" — mascara o problema
- NUNCA assumir bug e de camada unica sem rastrear da UI ate o banco
- NUNCA considerar fix de permissao completo sem testar cada role afetada
- NUNCA marcar como resolvido se apenas alguns usuarios estao corrigidos

## Quality Gate
- [ ] Causa raiz identificada (nao apenas sintoma)?
- [ ] Investigou se existem multiplas causas independentes?
- [ ] Rastreou todas as camadas afetadas (UI, API, config, dados)?
- [ ] Verificou consistencia de permissoes em toda a cadeia (JWT → RLS)?
- [ ] Fix resolve o problema sem criar novos?
- [ ] Fix verificado (rodou cenario que falhava)?
- [ ] Deploy Gap descartado (versao com fix esta servindo em prod)?
- [ ] errors-log.md atualizado com TODAS as causas?

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [andregusman-raiz](https://github.com/andregusman-raiz)
- **Source:** [andregusman-raiz/a-gusman-claude](https://github.com/andregusman-raiz/a-gusman-claude)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-andregusman-raiz-a-gusman-claude-ag-depurar-erro
- Seller: https://agentstack.voostack.com/s/andregusman-raiz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.