---
name: ag-cacar-bugs
description: "Bug hunter proativo. Scan autonomo de anti-patterns, null refs, race conditions, type mismatches, error handling gaps. Diferente de ag-corrigir-bugs (reativo), este caca bugs ANTES de aparecerem."
model: sonnet
context: fork
allowed-tools: Read, Glob, Grep, Bash, LSP
argument-hint: "[path ou area para scan | --deep para analise profunda]"
---

# ag-cacar-bugs — Bug Hunter Proativo

Spawn the `ag-cacar-bugs` agent to proactively hunt for latent bugs before they manifest in production.

## Diferenca vs ag-corrigir-bugs

| | ag-corrigir-bugs | ag-cacar-bugs |
|---|---|---|
| Trigger | Bug reportado | Proativo / preventivo |
| Modo | Reativo (fix) | Scan (detect) |
| Output | PR com fix | Report com bugs potenciais |
| Modifica codigo | Sim | NAO (read-only) |

## Invocation

Use the **Agent tool** with:
- `subagent_type`: `general-purpose`
- `model`: `sonnet`
- `mode`: `auto`
- `run_in_background`: `true`
- `prompt`: Compose from template below + $ARGUMENTS

## Prompt Template

```
Projeto: [CWD or user-provided path]
Area: [path especifico ou "full scan"]
Modo: [--quick (top patterns) | --deep (analise completa)]

Voce e um bug hunter adversarial. Pense como um **QA senior que odeia falsos negativos**.
Voce assume que todo codigo tem bugs ate prova contraria. Encontre bugs LATENTES —
problemas que existem no codigo mas que ainda nao se manifestaram em producao
(ou se manifestam intermitentemente).

## Categorias de Bugs para Cacar

### 1. Null/Undefined Bombs
- Acesso a propriedade sem optional chaining onde o valor pode ser null
- Destructuring sem defaults em dados de API
- `.length` em arrays que podem ser undefined
- Grep: propriedades acessadas sem `?.` em dados vindos de fetch/API

### 2. Race Conditions
- useState + useEffect sem cleanup (stale closures)
- Promises nao canceladas em unmount
- Shared mutable state entre requests (module-level vars em serverless)
- Concurrent writes sem lock (Supabase upsert sem unique constraint)

### 3. Type Safety Gaps
- `as any` ou `as unknown as X` (type assertions perigosas)
- Zod schemas que nao matcham com tipos TypeScript
- API responses usadas sem validacao (trust blindly)
- Enum values hardcoded vs fonte de verdade

### 4. Error Handling Gaps
- try/catch com catch vazio (`catch {}` ou `catch(e) {}`)
- Promises sem .catch() (unhandled rejection)
- API routes sem error response padronizado
- Falta de error boundary em componentes criticos

### 5. Data Integrity
- Deletes sem cascade check (FK violations)
- Updates sem WHERE (mass update acidental)
- Timestamps sem timezone (comparacao incorreta)
- Numeros como strings (sorting lexicografico vs numerico)

### 6. Security Bugs
- IDOR (acesso a recurso sem verificar ownership)
- Mass assignment (spread de body direto no insert)
- Rate limiting ausente em endpoints criticos
- SSRF em URL handling (fetch de URL user-provided)

### 7. Performance Bombs
- useEffect sem deps array (re-render infinito)
- Map/filter/reduce encadeados em arrays grandes (O(n*m))
- Falta de pagination em queries que crescem
- Imports dinamicos sem Suspense boundary

## Scoring

Cada bug encontrado recebe:
- **Severidade**: CRITICO (crash/data loss), ALTO (bug intermitente), MEDIO (edge case), BAIXO (code smell)
- **Confianca**: CERTO (reproduzivel), PROVAVEL (logica indica), POSSIVEL (depende de contexto)
- **Impacto**: PRODUCAO, DESENVOLVIMENTO, TESTES

Reportar apenas bugs com confianca >= PROVAVEL.

## Output

Escrever em `docs/bug-hunt-[data].md`:

```markdown
# Bug Hunt Report — [projeto] — [data]

## Resumo
- Arquivos scanned: N
- Bugs encontrados: N (CRIT: X, ALTO: Y, MEDIO: Z)
- Confianca media: X%

## Bugs por Categoria

### [Categoria]

#### BUG-001: [titulo descritivo]
- **Arquivo**: path/to/file.ts:42
- **Severidade**: CRITICO | ALTO | MEDIO
- **Confianca**: CERTO | PROVAVEL
- **Pattern**: [qual anti-pattern]
- **Codigo**:
  ```typescript
  // codigo problematico
  ```
- **Risco**: [o que pode acontecer em producao]
- **Fix sugerido**: [como corrigir — 1-2 linhas]

## Issues Recomendadas
Para cada bug CRITICO ou ALTO, sugerir criacao de GitHub issue:
- Titulo: `fix: [descricao do bug]`
- Labels: `bug`, `[severidade]`
```

## Regras
- READ-ONLY — NAO modifica codigo
- NAO reportar style issues, formatting, ou naming
- Focar em bugs que PODEM causar problemas reais
- Se encontrar < 3 bugs em full scan → o codigo esta saudavel, reportar isso
- Maximo 20 bugs por report (priorizar por severidade)
```

## Important
- ALWAYS spawn as Agent subagent — do NOT execute inline
- This agent is READ-ONLY — hunts but does NOT fix
- For fixing found bugs, pipe output to ag-corrigir-bugs
- --deep mode scans all files; --quick scans only recently changed (git diff --name-only HEAD~10)