From claudex-forge
Pipeline de debug em 3 fases com 5 agentes para caçar bugs num componente/rota/módulo/arquivo e em TODOS os seus componentes relacionados (hooks, services, edge functions/funções de backend, tabelas/migrations). Versão híbrida que une modos de falha estrutural, checagem de complexidade e procedimento de migrations classificado com regra de evidência transversal, adversário semântico, checklists condicionais por stack e validator cético com proteção estrutural. Auto-detecta stack pelo manifesto e adapta checklists (Supabase, Prisma, Next.js, etc). Fase 1 spawna 3 bug hunters em paralelo (frontend, backend, contratos/integração), Fase 2 spawna 1 cross-validator com dois passes (cético operacional + estrutural-friendly), Fase 3 spawna 1 consolidator com plano de correção ordenado + migrations classificadas. Mudanças de banco só são aplicadas com autorização explícita. É o caminho de bug padrão do /claudex-forge (Fase 0). Acionar quando o usuário mencionar "/findbugs", "findbugs", "claudex-forge:findbugs", "/ultrabugfinder", "ultrabugfinder", "manda o pipeline completo de bug", "debuga essa rota inteira", "debuga esse componente e tudo que ele usa", "caça bugs em [X] e nos relacionados", "pipeline de debug em 3 fases", "encontra todos os bugs desse fluxo", "auditoria profunda de bug" — mesmo sem citar literalmente o nome. NÃO acionar em menções casuais a "bug", "debug" ou "erro" sem alvo claro, nem em pedidos de review geral de código.
How this skill is triggered — by the user, by Claude, or both
Slash command
/claudex-forge:findbugsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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é...
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:
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.
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.
[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
ANTES de spawnar qualquer agente, pergunte ao usuário (texto direto na conversa):
Qual componente você quer que eu avalie?
- O componente aberto/em contexto agora (eu pego o arquivo mais recente da conversa)
- Um componente novo — me passa o caminho do arquivo
Responde o número ou cola o caminho.
Aguarde a resposta. Com a resposta:
.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.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:
- Rodar mesmo assim (5 agentes)
- Análise mais leve — eu mesmo leio o componente e os filhos diretos e reporto
- Cancelar
Aguarde a escolha. Só siga para a Fase 1 se o usuário escolher 1 ou se o componente realmente justificar.
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 geradosskills/claudex-forge/references/boas-praticas.md — convenções e regras do projetoEsses 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).
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.
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.
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:
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.
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.
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
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
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.
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.
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.
Spawne 1 agente (subagent_type: "general-purpose"). Cole o template e substitua [OUTPUT_AGENTE_4] pelo relatório integral do Cross-Validator.
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
Mostre o relatório final do Agente 5 integralmente ao usuário. Não resuma — o Agente 5 já fez esse trabalho.
Aguarde autorização antes de aplicar qualquer fix, a menos que o usuário tenha dito explicitamente "aplica os fixes" ou equivalente.
Ao aplicar:
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:
Classifique cada mudança:
Valide a proposta contra best practices do tooling do projeto:
supabase:supabase-postgres-best-practices se disponívelCorrija a proposta se necessário. Exemplos:
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.
Mostre o SQL/script ao usuário com:
references/boas-praticas.md, se existir)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.
Aplicação: branch + commit do script + PR. Migration só roda em produção depois do PR aprovado, igual qualquer mudança no projeto.
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.
npx claudepluginhub cassianodiniz/cassiano.diniz --plugin claudex-forgeGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.