findbugs

findbugs — Pipeline de debug em 3 fases / 5 agentes (híbrido)

Esta skill orquestra 5 agentes em sequência para caçar bugs reais num componente e em toda a sua cadeia de dependências (frontend + hooks + services + funções de backend + banco, se houver). O foco é achar coisas que causam crash, dados errados, perda de dados, vazamento entre escopos de usuário, ou bugs disparáveis em fluxo normal de uso — não é code review, não é refactor, não é review estético.

O que ela une:

• Regra de evidência transversal + adversário semântico + checklists condicionais por stack → cobertura forte de bugs cross-layer e bugs disparáveis em fluxo normal de usuário
• Modos de falha estrutural com proteção no validator → captura também bugs estruturais (CASCADE, atomicidade, transações) que um validator cético rebaixaria por falta de "cenário de uso comum"
• Checagem de complexidade + procedimento de migrations classificado → evita overkill em componente trivial e dá segurança ao aplicar fixes que tocam banco
• Genérica por design: detecta stack pelo manifesto e ativa os checklists relevantes (Supabase, Prisma, Next.js API routes, Edge Functions, etc)

Pré-requisito: roda dentro de um repo git. Detecta a stack do projeto pelo manifesto (package.json/pyproject.toml/Cargo.toml/go.mod/etc) e pelos diretórios presentes (supabase/, prisma/, api/, etc) e adapta os checklists.

Quando usar

Use quando o usuário digitar /findbugs (ou /ultrabugfinder) ou pedir explicitamente uma auditoria profunda de bugs num componente. Se o usuário só falou "tem bug aqui" sem alvo claro, pergunte qual componente antes de invocar — pipeline em alvo errado é desperdício.

Se o usuário quer algo mais leve que o pipeline completo, ofereça uma análise direta em vez de rodar este fluxo.

---

Fluxo geral

[Passo 0]   Perguntar qual componente avaliar
[Passo 0.1] Checagem de complexidade (oferecer análise leve se trivial)
[Passo 0.2] Carregar contexto do projeto + detectar stack e ativar checklists condicionais
    ↓
[Fase 1] 3 agentes em PARALELO (mesma mensagem, 3 tool calls Agent simultâneas):
         Agente 1: Frontend Bug Hunter
         Agente 2: Backend Bug Hunter (com Modos de Falha Estrutural)
         Agente 3: Contract & Integration Bug Hunter (com Adversário Semântico)
    ↓
[Fase 2] Agente 4: Cross-Validator (passe cético + passe estrutural-friendly)
    ↓
[Fase 3] Agente 5: Consolidator & Fix Planner
    ↓
[Passo 4] Apresentar relatório final
         Aplicar fixes de código mediante autorização (ordem por dependências)
         Migrations seguem procedimento classificado (aditiva/destrutiva) com autorização explícita

---

Passo 0 — Perguntar qual componente avaliar

ANTES de spawnar qualquer agente, pergunte ao usuário (texto direto na conversa):

Qual componente você quer que eu avalie?

1. O componente aberto/em contexto agora (eu pego o arquivo mais recente da conversa)
2. Um componente novo — me passa o caminho do arquivo

Responde o número ou cola o caminho.

Aguarde a resposta. Com a resposta:

• Se opção 1: identifique o arquivo mais relevante no contexto recente (último arquivo aberto/editado que faça sentido — componente React .tsx/.jsx, módulo Python .py, módulo Rust .rs, etc, conforme a stack). Se houver ambiguidade, liste 2–3 candidatos e peça confirmação.
• Se opção 2 (ou caminho direto): use o caminho fornecido.

Passo 0.1 — Checagem de complexidade

Antes de avançar para a Fase 1, leia o componente e avalie se vale o pipeline completo. Se o componente for trivial (puramente visual, sem estado próprio, sem queries/mutations, sem hooks customizados, sem formulário, < ~80 linhas de lógica real), avise o usuário:

Esse componente parece simples (sem estado/queries/lógica). O pipeline de 5 agentes pode ser overkill. Quer:

1. Rodar mesmo assim (5 agentes)
2. Análise mais leve — eu mesmo leio o componente e os filhos diretos e reporto
3. Cancelar

Aguarde a escolha. Só siga para a Fase 1 se o usuário escolher 1 ou se o componente realmente justificar.

Passo 0.2 — Carregar contexto do projeto + detectar stack e ativar checklists

Primeiro, leia o contexto configurado (se existir):

• claudex.config.json na raiz do plugin — stack declarada (stack_frontend, stack_backend, stack_database)
• skills/claudex-forge/references/arquitetura.md — schema do banco, rotas, componentes principais, onde ficam funções serverless e tipos gerados
• skills/claudex-forge/references/boas-praticas.md — convenções e regras do projeto

Esses arquivos são preenchidos no setup do plugin e são a fonte primária de "onde fica o quê" no projeto. Use-os pra instanciar os prompts dos agentes (paths reais de funções serverless, tipos do banco, regras do projeto).

Depois, valide no código (o contexto pode estar desatualizado): leia o manifesto do projeto e a estrutura de diretórios para identificar quais checklists condicionais ativar:

Sinal no projeto	Checklist a ativar
supabase/ presente, @supabase/supabase-js em deps	Supabase (RLS, edge functions, types.ts desync, limite 1000, Realtime, Storage)
prisma/ presente, prisma em deps	Prisma (transações, findUnique semantics, $transaction, schema vs migration drift)
app/api/ ou pages/api/ em Next.js	Next API routes (validação de input, auth middleware, edge runtime gotchas)
@tanstack/react-query em deps	React Query (queryKey staleness, invalidation, optimistic)
redux, zustand, jotai em deps	State management (mutation direta, selectors stale)
next.config.* + app/	Next.js App Router (RSC vs Client, server actions, dynamic = force-dynamic)
Sem nenhum sinal claro	Genérico (sem checklist específico, agentes operam só com o framework genérico)

Se a detecção no código divergir do claudex.config.json/arquitetura.md, confie no código e sugira atualizar os arquivos de contexto. Se a stack não tiver checklist pronto e os arquivos de contexto não mapearem os equivalentes (onde ficam as funções backend, onde ficam os tipos do banco), pergunte ao usuário antes de spawnar os agentes 2 e 3 — e sugira registrar as respostas em references/arquitetura.md pra não precisar perguntar de novo.

Documente internamente quais checklists vai ativar e injete no prompt do agente correspondente (especialmente Agente 2 e Agente 3).

---

REGRAS TRANSVERSAIS (aplicam a TODOS os agentes)

Regra 1 — Evidência operacional

Para classificar como bug confirmado, o agente precisa: (a) citar arquivo:linha; (b) articular cenário concreto (input, estado inicial, sequência de ações, resultado incorreto). Se faltar (a) ou (b), classifique como suspeito.

Regra 2 — Proteção estrutural

Exceção à Regra 1: bugs estruturais verificáveis no schema/migration/policy/contrato podem ser classificados como bug confirmado mesmo sem cenário de uso comum, desde que o agente cite o arquivo+linha do schema/migration/policy violado e descreva o modo de falha (ex: "transação ausente em mutation composta — falha intermediária deixa estado inconsistente"). Isso protege CASCADE silencioso, atomicidade, ON DELETE, FOREIGN KEY mal configurada, etc.

Regra 3 — Sem refactor, sem estética PRÓPRIA

Não proponha refactor, melhoria estética ou preferência arquitetural própria sua. Se algo é "feio mas funciona pelo seu gosto", ignore.

EXCEÇÃO — violação de regra documentada do projeto: se você encontra código que viola explicitamente uma regra escrita em CLAUDE.md, AGENTS.md, .claude/rules/, CONTRIBUTING.md, skills/claudex-forge/references/boas-praticas.md ou equivalente, entra como bug se e somente se a regra documenta impacto observável (comportamento divergente entre lugares, inconsistência visível ao usuário, manutenção quebrada por divergência). Severidade:

• MEDIUM se causa divergência cross-arquivo (mesmo conceito tratado de jeito diferente em ≥2 lugares — ex: toast use-toast aqui e sonner ali)
• LOW se causa inconsistência em apenas 1 arquivo sem efeito cascata

Citação obrigatória: regra violada (arquivo+seção) + arquivo:linha onde foi violada + impacto observável concreto (não só "viola a regra X"). Sem impacto observável documentado na regra, NÃO entra como bug — é review.

---

FASE 1 — Spawne estes 3 agentes em PARALELO

Crítico: spawne os 3 agentes em uma única mensagem com 3 tool calls Agent simultâneas. Não sequencial. Use subagent_type: "general-purpose" para os três. Substitua [CAMINHO_DO_COMPONENTE] pelo caminho obtido no Passo 0 e [CHECKLIST_STACK] pela lista de checklists ativados no Passo 0.2.

---

Agente 1: Frontend Bug Hunter

Investigue bugs de frontend para o componente [CAMINHO_DO_COMPONENTE] e para os componentes associados. Leia o arquivo inteiro, todos os componentes filhos importados, e os hooks que usa.

FOCO: apenas coisas que causam ERRO, comportamento incorreto, crash, ou dados errados para o usuário. Não é review de código.

REGRAS TRANSVERSAIS (obrigatórias):
- Bug confirmado precisa citar arquivo:linha + cenário concreto (input, estado, sequência de ações, resultado incorreto)
- Sem cenário articulável → suspeito, não confirmado
- Sem refactor nem estética — só bug

INVESTIGAR:

1. ESTADO & HOOKS:
   - useEffect com dependências erradas → loops infinitos ou stale data
   - useEffect sem cleanup → listeners/subscriptions/timers vazando
   - Estado lido antes de ser setado (race conditions no mount)
   - setState em componente desmontado
   - Derived state dessincronizado da source of truth
   - useCallback/useMemo com dependências stale
   - **Estado entre aberturas de Dialog/Modal/Sheet/Wizard:** se o componente renderiza dentro de `<Dialog>`, `<Sheet>`, `<Drawer>` ou wizard com `Step`, verifique:
     1. Cada `useState` inicializado com valor não-vazio: o estado é resetado quando `open` muda de `false` pra `true`? Procure por `useEffect(() => { if (open) setFoo(initial) }, [open])` ou key remontando o componente
     2. Cada hook customizado (`useXForm`, `useYState`) que mantém estado: tem método `reset()` chamado no onOpenChange ou no `useEffect` de abertura?
     3. Se NÃO há reset explícito → bug confirmado: 2ª abertura herda valores da 1ª. Cite o hook/state + onde deveria resetar
   - **Race de buscas paralelas em campo único:** se um input dispara busca async (CEP, CPF, telefone, slug), procure flag de "última busca venceu" (`AbortController`, `requestId` incremental). Sem isso → 2 buscas rápidas em sequência podem terminar em ordem trocada e mostrar dado da busca antiga

2. PROPS & DADOS:
   - Props undefined/null acessados sem guard (.property de undefined = crash)
   - Destructuring que assume campos existentes mas backend pode não enviar
   - Array.map/filter/find em valor que pode ser undefined
   - Conversões de tipo incorretas (string vs number, date parsing, parseFloat com vírgula brasileira)
   - Objetos mutados diretamente em vez de criar cópia (referência compartilhada)

3. FORMULÁRIOS (componente contém `<input>`, `<textarea>`, `<select>`, `<form>` ou wrapper equivalente de UI lib):
   - Validação que permite dados inválidos passarem para submit
   - Submit sem proteção contra double-submit (clique + Enter + clique simultâneo em 2 botões de submit)
   - Campos controlados perdendo valor (value vs defaultValue misturados)
   - onBlur/onChange que corrompe o dado (sanitização/truncamento errado)
   - Reset de form que não limpa todos os campos
   - **CHECK OBRIGATÓRIO — NOT NULL crash:** para CADA campo do formulário que vai pro INSERT principal, faça este pareamento (não opcional, não "se aplicável"):
     1. Abra a migration que define a tabela alvo (use Grep: `CREATE TABLE.*<nome_da_tabela>` em supabase/migrations/ ou prisma/migrations/ ou equivalente)
     2. Identifique se a coluna correspondente é `NOT NULL` (sem `DEFAULT`)
     3. Se SIM, verifique se há validação no form que BLOQUEIA submit com valor falsy (string vazia, null, undefined, 0 quando 0 é inválido para o domínio)
     4. Se NÃO há validação OU a validação aceita falsy → **bug CONFIRMADO**. Cite `migration:linha NOT NULL` + `handleSubmit:linha sem validação` + cenário concreto (usuário envia form com campo X em branco → INSERT falha 23502 → tela de erro)
   - Voltar para etapa anterior em wizard/stepper + submeter de novo enquanto estado da etapa seguinte ainda existe → duplicate-create

4. CONDICIONAIS & FLUXO:
   - Branches que nunca executam (dead code que deveria executar)
   - catch vazio ou catch que engole o erro sem feedback ao usuário
   - Loading/error states não tratados (tela branca, dados stale)
   - Redirects/navegação que podem loopear
   - Condições de corrida entre múltiplos async operations

5. INTERAÇÃO:
   - Handlers que falham silenciosamente em certos estados
   - Botões enabled quando deveriam estar disabled (ou vice-versa)
   - Botões expostos em estados onde a ação não faz sentido (ex: Editar em registro cancelado)
   - Modais que não resetam estado ao fechar/reabrir
   - Inputs que aceitam valores fora do range esperado

COMO INVESTIGAR:
1. Leia o componente inteiro, trace cada state/effect.
2. Para cada handler: simule com dados válidos E inválidos E vazios E null.
3. Grep por padrões perigosos: `as any`, `!.`, `catch {}`, `catch (e) {}`, empty catch blocks.
4. Cruze com schema do backend (se disponível) para detectar campos NOT NULL que o form não valida.
5. Verifique se testes existentes (busque em __tests__/ ou tests/) cobrem cenários de erro.

FORMATO DE SAÍDA (obrigatório):
## Frontend Bugs: [ComponentName]
### Confirmados (cenário concreto articulado)
Para cada: [Arquivo:Linha] | Descrição | Cenário concreto que dispara | Impacto | Fix sugerido

### Suspeitos (alto risco, falta cenário ou premissa)
Para cada: [Arquivo:Linha] | Cenário de risco | Premissa não verificada que impede confirmar

### Gaps em Testes
Cenários de erro não cobertos que podem esconder bugs ativos

---

Agente 2: Backend Bug Hunter (com Modos de Falha Estrutural)

Investigue bugs de backend para o componente [CAMINHO_DO_COMPONENTE] e para os componentes associados. Trace TODA a cadeia: componente → hooks → services → funções de backend → banco/persistência.

FOCO: dados errados, perda de dados, vazamento entre escopos de usuário, erros de runtime, modos de falha estrutural.

CHECKLISTS DE STACK ATIVOS para este projeto: [CHECKLIST_STACK]

REGRAS TRANSVERSAIS (obrigatórias):
- Bug confirmado precisa citar arquivo:linha + cenário (de uso OU de modo de falha estrutural)
- IMPORTANTE — Proteção estrutural: bugs verificáveis no schema/migration/policy/contrato podem ser confirmados SEM cenário de uso comum, desde que você cite o arquivo+linha do schema/migration/policy e descreva o modo de falha (ex: "ON DELETE CASCADE em users.id derruba registros que deveriam preservar histórico"). Isso protege CASCADE silencioso, atomicidade, FK mal configurada, ausência de transação em mutation composta.
- Sem refactor nem estética — só bug

PASSO 1 — TRACE A CADEIA COMPLETA:
1. Leia o componente, identifique TODOS os hooks e services importados.
2. Para cada service: leia e identifique chamadas a banco/API/função de backend (fetch, axios, supabase client, prisma, etc — adapte pela stack).
3. Para cada função de backend chamada: localize e leia (pasta varia por projeto — `supabase/functions/`, `api/`, `app/api/`, `functions/`).
4. Se houver banco: liste tabelas/coleções envolvidas E leia as migrations relevantes.
5. Documente o fluxo: Componente → Hook → Service → Backend → Persistência.

**REGRA DE LEITURA PROFUNDA DE MIGRATIONS — componente >500 linhas:**
Quando o componente alvo tem mais de 500 linhas (use `wc -l`), os bugs estruturais costumam estar em migrations LATERAIS que nenhum hook/service citado importa diretamente (ex: trigger criado num arquivo, FK ON DELETE CASCADE definida em outro, CHECK constraint num terceiro). Por isso, não limite a leitura às migrations que aparecem na cadeia rastreada:
1. Para cada tabela na lista do passo 4, rode `grep -l '<nome_da_tabela>' supabase/migrations/` (ou caminho equivalente do tooling) — você obtém TODAS as migrations que tocam essa tabela
2. Leia cada uma delas integralmente, mesmo que o frontend não as importe
3. Procure especificamente: triggers, FOREIGN KEY ... ON DELETE/UPDATE, CHECK constraints, ALTER TABLE alterando default/nullable, índices únicos, RLS policies
4. Bugs descobertos aqui contam como Modo de Falha Estrutural (próximo passo) — citar a migration encontrada como evidência

PASSO 2 — INVESTIGAR (genérico):

1. QUERIES / FETCHES:
   - Filtros faltando que retornam dados de OUTROS usuários/escopos (CRÍTICO em apps multi-tenant)
   - .single() / findUnique() em query que pode retornar 0 ou N rows → crash
   - Filtro .eq() / WHERE com campo que pode ser null → resultado silenciosamente errado
   - Select sem campos necessários para o componente funcionar
   - Ordenação assumida mas não explícita
   - Paginação ausente em listas que podem crescer (timeout/OOM)
   - useQuery / SWR sem tratamento de error state → renderiza vazio em vez de mostrar erro
   - **Limit implícito do tooling em query usada como verificação total:** quando a query é usada pra "dedup" ou "checar duplicata" ou "validar unicidade" no frontend (ex: SELECT ... WHERE cpf=X → se vazio, OK pra inserir), verifique se o tooling tem limit implícito (Supabase = 1000, Firestore = default da query). Se o universo de dados puder exceder o limit, a verificação falha silenciosamente em conta grande. Bug confirmado se: query sem `.range()` explícito + usada como "se vazio então não existe" + tabela cresce com uso normal

2. MUTATIONS:
   - UPDATE/INSERT sem filtro de escopo (user_id, tenant_id, etc) → afeta dado de outro usuário
   - Upsert com chave de conflito errada → sobrescreve registro errado
   - DELETE sem confirmação de escopo suficiente
   - Campos undefined que viram null no banco → perda de dados em partial update
   - Mutation que falha silenciosamente (sem throw, sem toast, usuário pensa que salvou)
   - Falta de invalidação de cache após mutation (dados stale no client)
   - Invalidação de cache APENAS na queryKey da tabela mutada, esquecendo tabelas relacionadas (cross-tabela)

3. FUNÇÕES DE BACKEND (edge functions, lambdas, route handlers, API routes):
   - Input não validado → dados malformados causam 500
   - CORS: cabeçalhos faltando → request bloqueada no browser
   - Auth: rota que devia exigir token mas não exige; rota com verify_jwt/equivalente desabilitado
   - Race conditions em operações que deveriam ser atômicas (sem transação, sem lock)
   - Response com status 200 em cenário de erro → frontend não detecta falha
   - Erro interno vazando para o client (stack trace, dados sensíveis)

4. CACHE & STATE MANAGEMENT:
   - queryKey/cacheKey que não inclui parâmetros relevantes → dados de outro contexto
   - Stale data após mutation por falta de invalidação
   - Optimistic update que não reverte corretamente em caso de erro

PASSO 3 — MODOS DE FALHA ESTRUTURAL (lê schema/migrations):

5. CASCADE & FK:
   - ON DELETE CASCADE / SET NULL onde deveria ser RESTRICT (apaga dado que deveria preservar)
   - ON DELETE RESTRICT onde deveria ser CASCADE (deixa órfão)
   - FK ausente em coluna que deveria ter (referência solta → órfãos)

6. ATOMICIDADE & TRANSAÇÃO:
   - Mutation composta (vários INSERT/UPDATE relacionados) sem transação → falha intermediária deixa estado inconsistente
   - Mutation no frontend que dispara N chamadas separadas que deveriam ser atômicas (ex: criar pedido + criar itens + vincular pagamento)
   - Rollback parcial que não desfaz tudo que precisava desfazer
   - Lead-fantasma / registro-fantasma: criação cancelada deixa lixo persistido

7. TRIGGERS, RPC, RPCs RELACIONADAS:
   - Trigger ausente que mantém invariante (ex: status_pai depende de status_filhos) → drift por janelas de tempo
   - Trigger presente que mantém invariante mas com bug (cobre só UPDATE não INSERT, ou vice-versa)
   - RPC que deveria existir mas não existe (frontend chama, função não definida)
   - RPC com SECURITY DEFINER sem checagem interna de auth.uid()

8. INDEX & CONSTRAINT:
   - UNIQUE faltando em campo que deveria ser único (duplicatas)
   - CHECK constraint ausente em campo que aceita valores inválidos
   - Index faltando em coluna usada em WHERE/JOIN/ORDER BY de query quente

CHECKLIST CONDICIONAL — só aplique se [CHECKLIST_STACK] contém o item:

### Se Supabase:
- RLS: audite policies separadamente para SELECT, INSERT, UPDATE, DELETE. Verifique USING(true), recursão por chamar a própria tabela, comandos sem policy, FORCE ROW LEVEL SECURITY ausente em tabelas sensíveis.
- Realtime: cleanup de subscriptions no unmount, filtros do canal coerentes com a query inicial, replica identity configurada, vazamento entre escopos em eventos.
- Listas: verifique se o código assume "todos os registros" apesar do limite padrão de 1000 do Supabase.
- Storage: bucket policies, signed URLs (expiração longa, logada), path expondo IDs previsíveis, upload órfão sem INSERT correspondente.
- Types: dessincronia entre arquivo de tipos gerados (ex: src/integrations/supabase/types.ts) e o schema. Compare se acessível.
- Edge functions: createClient com service_role onde deveria repassar JWT do usuário (bypassa RLS), auth.uid() em contexto service_role retornando NULL, uso de cors.ts shared helper, verify_jwt no config.toml.

### Se Prisma:
- $transaction faltando em operações compostas
- findUnique vs findFirst: findUnique requer where com campo @unique, falha silenciosamente se não
- Migration drift: schema.prisma alterado sem migration correspondente
- Soft-delete simulado por flag mas queries não filtram → mostra "deletado"

### Se Next.js App Router / API routes:
- Server actions sem validação de input
- `dynamic = 'force-dynamic'` esquecido em rota que precisa
- Edge runtime usando API só de Node
- Cookies / headers lidos em RSC que precisa ser dynamic
- Vazamento de secret em prop serializada para Client Component

### Se React Query:
- queryKey sem todos os parâmetros relevantes (user.id, filters)
- staleTime/cacheTime errados pra dado que muda
- onSuccess que faz mutate em vez de invalidate

FORMATO DE SAÍDA (obrigatório):
## Backend Bugs: [ComponentName]
### Cadeia Rastreada
Componente → Hook(s) → Service(s) → Backend(s) → Persistência (com nomes reais dos arquivos)

### Confirmados (cenário operacional)
Para cada: [Arquivo:Linha] | Descrição | Cenário concreto que dispara | Impacto | Fix

### Confirmados (modo de falha estrutural)
Para cada: [Arquivo:Linha do schema/migration/policy] | Descrição | Modo de falha + por que é estrutural | Impacto | Fix
(Estes NÃO precisam de cenário de uso comum, só de evidência no schema.)

### Suspeitos
Para cada: [Arquivo:Linha] | Cenário de risco | Premissa não verificada

### Segurança (apenas bugs)
Violações concretas: rotas sem auth, PII em logs, scope isolation quebrada, secrets em código

---

Agente 3: Contract & Integration Bug Hunter (com Adversário Semântico)

Investigue bugs de CONTRATO e INTEGRAÇÃO para o componente [CAMINHO_DO_COMPONENTE] e para os componentes associados. Foque em bugs que existem nas FRONTEIRAS entre camadas — onde o frontend assume algo que o backend não garante, ou vice-versa.

FOCO: type mismatches entre camadas, regras do projeto violadas que causam bugs, contratos quebrados, divergências semânticas.

CHECKLISTS DE STACK ATIVOS: [CHECKLIST_STACK]

REGRAS TRANSVERSAIS (obrigatórias):
- Bug confirmado precisa citar arquivo:linha + cenário concreto
- Sem refactor nem estética

PASSO 1 — IDENTIFIQUE AS FRONTEIRAS:
1. Leia o componente e identifique os tipos TypeScript (ou equivalente — Python TypedDict, schema Zod/Joi/Yup, etc) usados para dados externos.
2. Leia os services que fornecem esses dados.
3. Compare os tipos do client com o schema real do dado (arquivo de tipos gerados se houver — types.ts, schema.prisma, OpenAPI spec, etc).
4. Se usa função de backend: compare o response type no client com o que a função realmente retorna.

PASSO 2 — INVESTIGAR:

1. TYPE MISMATCHES (client vs backend/banco):
   - Campo marcado required no tipo client mas nullable no banco → crash quando null chega
   - Campo marcado optional no tipo mas NOT NULL no backend → insert/update falha
   - Enum no client que não bate com constraint do banco → valor rejeitado
   - Campo numérico no tipo mas string no backend (ou vice-versa) → comparações erradas
   - Date handling: client espera ISO string mas backend retorna timestamp com timezone (ou outro formato)

2. CONTRATOS DE API:
   - Backend retorna campo que client não lê (dado perdido)
   - Client espera campo que backend não retorna (undefined access)
   - Error response com formato diferente do que o client faz catch
   - Backend mudou contrato mas client ficou com versão antiga

3. REGRAS DO PROJETO QUE CAUSAM BUGS (você é o GUARDIÃO único — Agentes 1 e 2 NÃO investigam este eixo):
**OBRIGATÓRIO ANTES DE INVESTIGAR:** leia CLAUDE.md, AGENTS.md, GEMINI.md, CONTRIBUTING.md, ARCHITECTURE.md, .claude/rules/, .cursor/rules e skills/claudex-forge/references/boas-praticas.md (se existirem). Liste as regras documentadas com impacto observável antes de cruzar com o código.

Procure padrões internos que o projeto define como armadilhas:
   - Componente/helper proibido sendo usado em vez do padrão (ex: `<input type="date">` nativo em vez do DateInput documentado do projeto — impacto: comportamento de data divergente entre telas)
   - Toast/notificação importado de biblioteca legada em vez da oficial (impacto: estilos inconsistentes, futuro break ao remover legada)
   - RPCs proibidos chamados direto do frontend (impacto: bypass de segurança documentado)
   - Bypass de validação universal definida pelo projeto
   - Padrões de query/mutation que o projeto define como obrigatórios
   - Hooks customizados ignorados quando o padrão exige (ex: `useFormState` do projeto vs `useState` solto)
   - Cast com tipo local em vez de tipo gerado do schema (ex: `as MyLocalType` em vez de `Database['public']['Tables']['x']['Row']`)
   - **Anti-padrão específico:** filtros redundantes com camada já garantida pelo projeto (ex: `.eq('user_id', ...)` quando RLS já filtra E o CLAUDE.md proíbe — citar a regra. NÃO sugira ADICIONAR o filtro como fix de outro bug)

Para cada bug nesta categoria: cite a regra (arquivo+seção) + arquivo:linha violado + impacto observável descrito pela regra (NÃO só "viola regra X").

4. ADVERSÁRIO SEMÂNTICO (procura código que MENTE, não código que diverge em tipo):
   - Campos com mesmo nome e mesmo tipo mas significado diferente entre camadas
   - Unidades divergentes: kg vs g, minutos vs segundos, centavos vs reais, % vs decimal, metros vs cm
   - Timezone: banco em UTC vs frontend em horário local, query gte:hoje feita à noite pegando o dia seguinte em UTC
   - Datas sentinela como "1970-01-01" ou "0001-01-01" que passam em truthy checks
   - String vazia, 0, null, undefined com semântica diferente no mesmo campo entre lugares
   - Enums/status parcialmente tratados: alguém adicionou status novo mas só metade dos if/switch/maps foi atualizado
   - Truthy/falsy enganoso: 0, "", [], null, undefined tratados diferente
   - Booleanos derivados de strings/números ("true" vs true, 1 vs true, "S" vs "N")
   - parseFloat / parseInt com formato local (vírgula brasileira "1.234,56" quebra parseFloat)
   - startOfDay/endOfDay aplicado em horários diferentes entre arquivos (uma janela vê coisa que a outra não vê)
   - Códigos de país, moeda, idioma assumidos como BR/BRL/pt sem checar
   - Integração ativa vs legada: código que aponta pra uma integração ativa em alguns pontos e pra uma legada em outros (ex: provedores trocados onde só metade das chamadas migrou)

5. RACE CONDITIONS CROSS-LAYER:
   - Client dispara 2 mutations concorrentes que conflitam no backend
   - Cache invalidation timing: query refetch antes da mutation completar
   - Optimistic update no client + backend lento → estado temporariamente inconsistente
   - Estado de "loading/pending" no client persiste mesmo quando backend retornou erro de rede (loader infinito)

COMO INVESTIGAR:
1. Abra o arquivo de tipos gerados (se houver) e compare tipos das entidades envolvidas.
2. Para cada campo usado no componente: verifique se nullable na fonte de verdade.
3. Para cada campo numérico/data: declare unidade/formato/semântica esperada em cada camada e compare. Match de tipo não basta — exija match SEMÂNTICO.
4. Grep por padrões problemáticos definidos no CLAUDE.md/AGENTS.md/boas-praticas.md do projeto.
5. Compare schema de validação client-side (Zod/Joi/Yup) com o schema do backend.

FORMATO DE SAÍDA (obrigatório):
## Contract & Integration Bugs: [ComponentName]
### Mismatches Encontrados
Para cada: [Arquivo Frontend:Linha] vs [Tipo/Schema:Campo] | O que diverge | Cenário concreto | Impacto

### Divergências Semânticas
Para cada: Campo | Camada A (significado) vs Camada B (significado) | Cenário concreto que dispara o bug

### Regras do Projeto Violadas que Causam Bugs
Para cada: [Regra] | [Arquivo:Linha] | Bug resultante | Cenário concreto

### Race Conditions Cross-Layer
Para cada: Cenário concreto | Arquivos envolvidos | Impacto no usuário

### Suspeitos
Para cada: O que pode divergir | Premissa não verificada que impede confirmar

Após os 3 agentes retornarem, guarde os 3 outputs completos (texto integral) e avance para a Fase 2. Não resuma os relatórios — o Cross-Validator precisa dos detalhes originais.

---

FASE 2 — Cross-Validator (Critic) — dois passes

Spawne 1 agente (subagent_type: "general-purpose"). No campo prompt, cole o template abaixo e substitua [OUTPUT_AGENTE_1], [OUTPUT_AGENTE_2], [OUTPUT_AGENTE_3] pelos textos integrais retornados pelos 3 bug hunters.

Agente 4: Cross-Validator (Critic)

Você é o agente validador. Recebeu os relatórios de 3 bug hunters que analisaram o mesmo componente. Seu trabalho tem 3 partes: REFUTAR, DESCOBRIR, CLASSIFICAR.

1. REFUTAR — DOIS PASSES:

   Passe A — Cético operacional (default):
   Para cada bug "confirmado por cenário operacional", refute APENAS se faltar UM destes três critérios objetivos:
      a. Linha verificável no código (você abriu o arquivo:linha e o código citado existe)
      b. Modo de falha articulado (input, estado inicial, sequência de ações → resultado incorreto descrito)
      c. Impacto identificável em fluxo de uso (papel do usuário + onde ele toca isso na UI/API)
   Se os 3 critérios estão presentes, **MANTENHA a severidade declarada pelo hunter**. NÃO rebaixe CRITICAL pra HIGH só porque o cenário foi descrito de forma curta — verifique o impacto objetivo, não a riqueza da prosa.
   Se faltar (a): refute como falso positivo ou alucinação.
   Se faltar (b) OU (c): rebaixe pra "suspeito".

   Passe B — Estrutural-friendly (PROTEÇÃO):
   Para cada bug "confirmado por modo de falha estrutural" (CASCADE silencioso, atomicidade, FK mal configurada, trigger ausente, UNIQUE faltando, transação ausente em mutation composta), aplique régua diferente:
   Mantenha como bug validado se:
      a. Você leu o schema/migration/policy citado (arquivo:linha)
      b. O modo de falha é verificável estaticamente no código (não precisa de cenário de uso comum)
      c. A consequência descrita é coerente com o que o schema/migration define
   NÃO refute esses bugs por falta de "cenário de usuário comum" — modos de falha estrutural são reais mesmo quando o caminho de uso é raro. Refute APENAS se o schema/migration não confirma o que o hunter descreveu.

   **PROIBIÇÃO ESPECÍFICA — não rebaixar por brevidade:**
   Um bug com (linha verificável + impacto operacional descrito + severidade CRITICAL declarada pelo hunter) NÃO pode ser rebaixado pra HIGH só porque você acha que "o cenário poderia ser mais elaborado". Severidade é função de IMPACTO, não de quantidade de palavras. Releia a régua de classificação abaixo: se o impacto bate com CRITICAL, mantenha CRITICAL.

2. DESCOBRIR:
Ao cruzar os achados dos 3 hunters, procure bugs que NENHUM deles percebeu, especialmente bugs que só aparecem quando você olha a interação entre frontend, backend e contratos juntos. Cruze:
   - Frontend valida X mas backend permite Y (ou vice-versa)
   - Trigger no banco que altera dado que o frontend assume imutável
   - Cache invalidation que esquece tabela relacionada
   - Adversário semântico cross-arquivo (mesma função usada com unidades diferentes)

2.5. DEDUP DE VARIANTES (obrigatório):
Antes de classificar, identifique bugs que são VARIANTES DA MESMA RAIZ. Variantes têm:
   - Mesma causa estrutural (mesma função, mesmo modo de falha, mesma constraint violada)
   - Mesmo fix (uma correção resolve ambos)
   - Mesma cadeia de impacto, só mudando o "campo" (ex: "23505 silenciado em telefone" + "23505 silenciado em instagram" = mesma raiz "INSERT em contatos sem catch de 23505", basta UM fix)

Quando detectar variantes: consolide em UM bug com seção "Variantes" listando os campos/contextos afetados. NÃO conte cada variante como bug independente. NÃO infle CRITICAL multiplicando-os. Se a raiz é 1 bug, é 1 bug — variante é nota.

3. CLASSIFICAR:
Para cada bug que sobrevive:
   - CRITICAL: vazamento entre escopos de usuário, bypass de auth, perda de dados críticos, dados críticos salvos errado silenciosamente, crash em fluxo principal de uso normal
   - HIGH: crash em fluxo secundário comum, dados errados exibidos ao usuário, comportamento incorreto sem workaround, modo de falha estrutural com impacto direto em dado de usuário
   - MEDIUM: crash em edge case real, UX quebrada com workaround, divergência de padrão que pode confundir, modo de falha estrutural com impacto indireto
   - LOW: cosmético, edge case muito improvável, dívida técnica que vira bug só em condição extrema

A classificação considera TIPO + IMPACTO (frequência, reversibilidade, dado crítico vs cosmético).

RELATÓRIOS RECEBIDOS:

===== AGENTE 1 — FRONTEND BUG HUNTER =====
[OUTPUT_AGENTE_1]

===== AGENTE 2 — BACKEND BUG HUNTER =====
[OUTPUT_AGENTE_2]

===== AGENTE 3 — CONTRACT & INTEGRATION BUG HUNTER =====
[OUTPUT_AGENTE_3]

COMO VALIDAR:
1. Para cada bug "confirmado": leia o arquivo+linha citados e verifique com seus próprios olhos
2. Verifique se o "fix sugerido" realmente resolve ou introduz novo bug
3. Procure dependências entre bugs (fix de um pode resolver ou criar outro)
4. Identifique falsos positivos (hunter reportou bug mas o código está correto)

FORMATO DE SAÍDA (obrigatório):
## Cross-Validation Report: [ComponentName]

### Bugs Validados — Operacionais (sobreviveram ao passe cético)
Para cada: Severidade | [Arquivo:Linha] | Descrição | Cenário concreto que dispara | Por que não foi refutado

### Bugs Validados — Estruturais (sobreviveram ao passe estrutural)
Para cada: Severidade | [Arquivo:Linha do schema/migration/policy] | Descrição | Modo de falha estrutural | Por que não foi refutado

### Falsos Positivos (refutados)
Para cada: Bug original | Guarda/invariant/policy/fluxo que impede: "O código está correto porque Z"

### Rebaixados para Suspeitos
Para cada: Bug original | Premissa não comprovada que falta verificar

### Bugs Novos (descobertos no cruzamento)
Para cada: Severidade | Descrição | Cenário concreto OU modo de falha estrutural | Como descobri (quais achados cruzei)

### Dependências entre Bugs
Quais bugs estão conectados e qual ordem de fix evita regressão

Após o Agente 4 retornar, guarde o output completo e avance para a Fase 3.

---

FASE 3 — Consolidator & Fix Planner

Spawne 1 agente (subagent_type: "general-purpose"). Cole o template e substitua [OUTPUT_AGENTE_4] pelo relatório integral do Cross-Validator.

Agente 5: Consolidator & Fix Planner

Você é o agente final. Recebeu o relatório validado do Cross-Validator. Produza o relatório executável final.

RELATÓRIO DO CROSS-VALIDATOR:

[OUTPUT_AGENTE_4]

PRODUZIR:

1. RESUMO EXECUTIVO (3 linhas max):
   - Total de bugs por severidade
   - Área mais problemática
   - Risco principal se não corrigir

2. TABELA DE BUGS FINAL (ordenada por severidade, sem duplicatas):
   | # | Severidade | Camada | Arquivo:Linha | Bug | Cenário/Modo de falha | Fix |

   - "Camada" = Frontend / Backend / Schema / Contrato / Cross-layer
   - "Cenário/Modo de falha":
     - Para bugs operacionais: input + estado inicial + sequência de ações + resultado incorreto
     - Para bugs estruturais: arquivo do schema/migration + invariante violada
   - Se não conseguir articular nem cenário nem modo de falha estrutural, NÃO liste como bug confirmado; mova para "Riscos Residuais".

3. PLANO DE CORREÇÃO ORDENADO:
   - Ordem exata dos fixes (considerando dependências — não pode fixar B antes de A se B depende de A)
   - Para cada fix: arquivo a editar, o que mudar, e teste para validar
   - Agrupar fixes em commits coesos (1 commit por família de bug relacionado)
   - Indicar quais fixes podem ir em PR única vs precisam de PRs separadas (regra: migrations destrutivas vão em PR separada)
   - Estimativa qualitativa de cuidado: trivial / requer atenção / requer cuidado (NÃO usar tempo)

4. TESTES A ADICIONAR:
   - Para cada bug corrigido: teste que previne regressão
   - Cenário do teste + assertion esperada
   - Tipo de teste recomendado (unit, integration, e2e) baseado na natureza do bug

5. MIGRAÇÕES DE BANCO (se aplicável):
   - Liste cada mudança de banco necessária
   - Classifique: ADITIVA (CREATE TABLE/INDEX novo, ADD COLUMN nullable, nova função) ou DESTRUTIVA (DROP, ALTER TYPE, RENAME, mudança em policy/RLS existente, ADD COLUMN NOT NULL sem default, UPDATE em massa)
   - Para cada: SQL/script proposto + por que necessária + qual bug resolve + risco + como reverter
   - Destrutivas SEMPRE em PR separada com autorização específica

6. OBSERVAÇÕES SEM IMPACTO OPERACIONAL — pedem decisão de produto/arquitetura:
Esta seção existe pra capturar achados úteis que NÃO são bug. Não infle a tabela principal com isto. Exemplos do que entra aqui:
   - Campo/coluna existe no schema mas não é editável neste form (gap de feature)
   - Componente sem testes que talvez devesse ter
   - Tipo TS tem campo que ninguém usa (dívida)
   - Decisão arquitetural que o usuário pode querer revisitar (ex: form-único usado pra criar e editar quando o fluxo de edição é claramente diferente)

Para cada: O que observei | Por que vale considerar | Decisão pendente (do usuário, não sua)
NÃO classifique severidade aqui (não é bug). Se você está em dúvida se é bug ou observação, pergunte: tem impacto operacional documentado? Se NÃO, vai pra cá.

7. RISCOS RESIDUAIS:
   - Bugs "suspeitos" não confirmados mas que merecem monitoramento
   - Bugs sem cenário articulável nem modo de falha estrutural verificável (movidos da tabela principal)
   - Áreas adjacentes que podem ser afetadas pelos fixes

---

Passo 4 — Apresentar e (se autorizado) executar o plano

4.1 — Apresentar

Mostre o relatório final do Agente 5 integralmente ao usuário. Não resuma — o Agente 5 já fez esse trabalho.

4.2 — Fixes de código (frontend/backend/edge functions/etc)

Aguarde autorização antes de aplicar qualquer fix, a menos que o usuário tenha dito explicitamente "aplica os fixes" ou equivalente.

Ao aplicar:

• Siga a ordem exata do plano (dependências importam)
• Um commit por fix coeso (ou por grupo de fixes relacionados)
• Nunca commitar direto em main — seguir o workflow do CLAUDE.md do projeto (branch → commit → PR)

4.3 — Mudanças de banco de dados (REGRA ESPECIAL)

Se o plano inclui qualquer mudança de banco (nova tabela, coluna, constraint, index, policy, RPC, trigger, etc), NUNCA aplicar direto. Migrations são difíceis de reverter — uma mudança errada pode apagar dados, travar o sistema ou quebrar isolamento entre usuários/tenants.

Pular esta seção se o projeto não tem banco.

Procedimento obrigatório:

1. Classifique cada mudança:

   • Aditiva (baixo risco): CREATE TABLE/INDEX novo, ADD COLUMN nullable, nova função, novo trigger sem mudar comportamento existente
   • Destrutiva (alto risco): DROP, ALTER TYPE, RENAME, mudança em policy/RLS existente, ADD COLUMN NOT NULL sem default, UPDATE em massa, mudança em FK/CASCADE existente

2. Valide a proposta contra best practices do tooling do projeto:

   • Supabase: invocar skill supabase:supabase-postgres-best-practices se disponível
   • Prisma: checar padrões em prisma/schema.prisma e docs
   • Outro: documentação oficial do tooling

3. Corrija a proposta se necessário. Exemplos:

   • Adicionar policies de segurança se a tabela tem escopo por usuário
   • Criar índices em colunas usadas em WHERE/JOIN/ORDER BY
   • Usar IF NOT EXISTS / IF EXISTS para idempotência
   • Usar tipos apropriados (uuid para ids, timestamptz para datas com timezone)
   • Nunca editar migration já aplicada — sempre criar nova

4. Crie o arquivo da migration no caminho convencional do projeto (supabase/migrations/, prisma/migrations/, alembic/versions/) com nome seguindo o padrão, mas NÃO execute ainda.

5. Mostre o SQL/script ao usuário com:

   • Classificação (aditiva ou destrutiva)
   • O que faz, por que necessária, qual bug resolve
   • Riscos e como reverter (rollback SQL) se der ruim
   • Se altera arquivo de tipos gerados, avise que precisa regerar os tipos com o comando do seu stack (ver references/boas-praticas.md, se existir)

6. Aguarde autorização explícita ("aplica", "manda", "ok"). Sem autorização não rode. Para destrutivas, não aceitar autorização genérica anterior — pergunte especificamente sobre essa migration.

7. Aplicação: branch + commit do script + PR. Migration só roda em produção depois do PR aprovado, igual qualquer mudança no projeto.

---

Integração com o /claudex-forge

Quando rodado dentro do fluxo /claudex-forge (Fase 0, opção de bug), o relatório final do Agente 5 (plano de correção ordenado) é salvo em ${RUN_DIR}/0-findbugs-report.md e vira o input da Fase 1 — o plano de implementação ataca os bugs confirmados na ordem do plano de correção.

---

Notas operacionais

• Paralelismo é obrigatório na Fase 1. Spawnar os 3 agentes em mensagens separadas triplica o tempo sem ganho.
• Preserve outputs integralmente entre fases. Não resuma os relatórios antes de passar pro próximo agente — eles precisam dos detalhes originais (arquivos, linhas, fixes sugeridos) pra validar e consolidar.
• Se um dos hunters da Fase 1 não achar nada, ainda assim avance — o Cross-Validator pode encontrar bugs no cruzamento mesmo com hunter "vazio".
• Se o componente é trivial, o Passo 0.1 já filtrou — não rode o pipeline em wrapper de UI sem lógica.
• A proteção estrutural existe por design. Não a remova "pra ser mais cético" — bugs estruturais reais foram perdidos historicamente por validators que exigiam cenário de uso comum para CASCADE silencioso. A proteção é o que diferencia esta skill de uma versão só cética.