--- name: findbugs description: Pipeline de debug em 3 fases com 5 agentes para caçar bugs num componente e em todos os seus componentes relacionados (hooks, services, edge functions, tabelas). Acionamento EXCLUSIVO via invocação direta claudex-dev:findbugs — NÃO ativar em menções casuais a "bug", "debug", "erro" ou pedidos genéricos de análise de código. Só rodar quando o usuário digitar literalmente claudex-dev:findbugs. O fluxo é: pergunta qual componente avaliar (o que está em contexto ou um novo), spawna 3 bug hunters em paralelo (frontend, backend, contratos/integração), depois 1 cross-validator crítico, depois 1 consolidator com plano de correção ordenado. --- # FindBugs — Pipeline de Debug em 3 Fases Este 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 + edge functions + banco). O foco é achar coisas que causam crash, dados errados, perda de dados, ou vazamento entre usuários/tenants — **não é code review**. ## Quando usar **EXCLUSIVO para invocação direta `claudex:findbugs`.** Nunca acionar automaticamente mesmo se o usuário: - mencionar "bug", "debug", "erro", "problema" - pedir "revisar o código" (use `/revisao` ou outros skills para isso) - pedir análise geral de um componente Se o usuário quiser algo mais leve que o pipeline completo, ofereça uma abordagem mais simples em vez de rodar este fluxo. --- ## Fluxo geral ``` [Passo 0] Perguntar qual componente avaliar ↓ [Passo 0.1] Detectar stack — se não-Supabase, perguntar antes de prosseguir ↓ [Passo 0.2] Checagem de complexidade — se trivial, sugerir análise leve ↓ [Fase 1] 3 agentes em PARALELO (mesma mensagem): Agente 1: Frontend Bug Hunter Agente 2: Backend Bug Hunter Agente 3: Contract & Integration Bug Hunter ↓ [Fase 2] Agente 4: Cross-Validator (Critic) Recebe os 3 outputs da Fase 1 como contexto ↓ [Fase 3] Agente 5: Consolidator & Fix Planner Recebe o output do Agente 4 como contexto ↓ [Passo 4] Apresentar relatório final ao usuário Se houver mudanças de banco: aplicar seguindo boas práticas do Supabase Fixes de código: aguardar autorização (ou aplicar se o usuário já autorizou) ``` --- ## 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 de componente mais relevante no contexto recente da conversa (último arquivo aberto/editado que seja um componente React — `.tsx` em `src/`). Se houver ambiguidade, liste 2–3 candidatos e peça confirmação. - Se opção 2 (ou caminho direto): use o caminho fornecido. **Só avance para a Fase 1 depois de ter o caminho do componente alvo.** ### Passo 0.1 — Detecção de stack (antes de spawnar os agentes) Este pipeline tem **agentes que assumem stack Supabase** (Backend Bug Hunter lê `supabase/functions/`, queries Postgres; Contract Hunter lê `src/integrations/supabase/types.ts`). Antes de spawnar, **verifique se o projeto realmente usa Supabase**: ```bash # Detecção rápida (rodar a partir do worktree/repo do projeto): SUPA_FUNCTIONS_DIR=$([ -d "supabase/functions" ] && echo "yes" || echo "no") SUPA_TYPES_FILE=$([ -f "src/integrations/supabase/types.ts" ] && echo "yes" || echo "no") HAS_SUPABASE_DEP=$(grep -q '"@supabase/supabase-js"' package.json 2>/dev/null && echo "yes" || echo "no") # Detecta concorrentes HAS_FIREBASE=$(grep -q '"firebase"' package.json 2>/dev/null && echo "yes" || echo "no") HAS_PRISMA=$([ -d "prisma" ] && echo "yes" || echo "no") HAS_DRIZZLE=$(grep -q '"drizzle-orm"' package.json 2>/dev/null && echo "yes" || echo "no") ``` **Se todos os 3 sinais de Supabase forem `yes`:** prosseguir normalmente, sem dizer nada (modo silencioso). **Se Supabase NÃO foi detectado** (paths ausentes ou outro provedor detectado), pause e mostre ao usuário: ``` 🔍 Detectei que este projeto não parece usar Supabase. A findbugs tem 2 agentes (Backend Bug Hunter, Contract Hunter) que assumem Supabase nos passos de investigação: - Leitura de edge functions em `supabase/functions/` - Comparação de tipos em `src/integrations/supabase/types.ts` - Queries SQL Postgres - Uso da lib `@supabase/supabase-js` Seu stack detectado: Como prefere: 1. Rodar mesmo assim — os agentes vão pular os passos Supabase-específicos e investigar só o que é genérico (estado, props, condicionais, etc). Resultado vai ser mais raso no backend/contratos. 2. Cancelar — pra eu adaptar os prompts dos agentes 2 e 3 pro seu stack antes de rodar (preciso saber qual é seu equivalente a edge functions e onde ficam os tipos do banco). 3. Continuar mesmo assim e te aviso depois quais passos foram pulados. ``` Aguarde a escolha. Se escolher 2 (cancelar pra adaptar), pergunte: - Onde ficam as suas funções backend (paths)? - Onde ficam os tipos do banco (gerado por Prisma? Drizzle? manual)? - Como roda queries (ORM? cliente direto?) Com essas respostas, adapte os prompts dos Agentes 2 e 3 antes de spawnar. ### Passo 0.2 — Checagem de complexidade (antes de spawnar 5 agentes) 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 (tem estado, queries, lógica de negócio, etc.). --- ## REGRA DE EVIDÊNCIA (transversal a todos os agentes) Não chame algo de bug confirmado sem citar arquivo:linha e explicar o caminho concreto até o erro. Se depender de premissa externa não verificada, classifique como suspeito. Não proponha refactor, melhoria estética ou preferência arquitetural. O escopo é bug, não review. **Trava anti-presunção — causa que depende de runtime/dado/integração só é "confirmada" se TESTADA contra o sistema real.** Causa é FATO: se verifica, não se chuta. Quando o erro depende de estado externo ao código (token válido?, config ligada?, API externa respondendo?, registro existe no banco?), ler o código não confirma nada — só testar contra o real (query no banco, request na API/serviço, reproduzir o caso). Sem esse teste, a causa entra como **suspeito**, nunca como diagnóstico fechado. ## Fase 1 — 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. Cole os prompts abaixo **verbatim** no parâmetro `prompt` de cada Agent call. --- ### 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. 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 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) - Objetos mutados diretamente em vez de criar cópia (referência compartilhada) 3. FORMULÁRIOS (se aplicável): - Validação que permite dados inválidos passarem para submit - Submit sem proteção contra double-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 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) - 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. Verifique se testes existentes (busque em __tests__/) cobrem cenários de erro FORMATO DE SAÍDA (obrigatório): ## Frontend Bugs: [ComponentName] ### Confirmados (certeza que é bug) Para cada: [Arquivo:Linha] | Descrição | Como reproduzir | Impacto | Fix sugerido ### Suspeitos (alto risco, precisa confirmar) Para cada: [Arquivo:Linha] | Cenário de risco | Por que suspeita ### Gaps em Testes Cenários de erro não cobertos que podem esconder bugs ativos ``` --- ### Agente 2: Backend Bug Hunter ``` Investigue bugs de backend para o componente [CAMINHO_DO_COMPONENTE] e para os componentes associados. Trace TODA a cadeia: componente → hooks → services → edge functions → banco. FOCO: dados errados, perda de dados, vazamento entre usuários/tenants, erros de runtime. Não é review. 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 Supabase (.from(), .rpc(), fetch a edge functions) 3. Para cada edge function chamada: leia em supabase/functions/ 4. Liste as tabelas envolvidas 5. Documente o fluxo: Componente → Hook → Service → EdgeFn → Tabela PASSO 2 — INVESTIGAR: 1. QUERIES: - Filtros faltando que retornam dados de OUTROS usuários/tenants (CRÍTICO) - .single() em query que pode retornar 0 ou N rows → crash - .eq() 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 2. MUTATIONS: - UPDATE/INSERT sem filtro por tenant/owner (ex: user_id, org_id) → afeta outro usuário - Upsert com onConflict errado → sobrescreve registro errado - DELETE sem confirmação de escopo suficiente - Campos undefined que viram null no banco → perda de dados existentes 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 React Query) 3. EDGE FUNCTIONS: - Input não validado → dados malformados causam 500 - CORS: verifica se usa cors.ts shared helper (senão, request bloqueada) - Auth: verifica verify_jwt no config.toml + se usa authz.ts - Race conditions em operações que deveriam ser atômicas - 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 & REACT QUERY: - queryKey que não inclui parâmetros relevantes → dados de outro contexto - Stale data após mutation por falta de invalidateQueries - Optimistic update que não reverte corretamente em caso de erro FORMATO DE SAÍDA (obrigatório): ## Backend Bugs: [ComponentName] ### Cadeia Rastreada Componente → Hook(s) → Service(s) → Edge Function(s) → Tabela(s) (com nomes reais dos arquivos) ### Confirmados Para cada: [Arquivo:Linha] | Descrição | Impacto (dados errados/perda/vazamento/crash) | Fix ### Suspeitos Para cada: [Arquivo:Linha] | Cenário de risco ### Segurança (apenas bugs) Violações concretas: RPCs proibidos no frontend, PII em logs, scope isolation quebrada ``` --- ### Agente 3: Contract & Integration Bug Hunter ``` 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. PASSO 1 — IDENTIFIQUE AS FRONTEIRAS: 1. Leia o componente e identifique os tipos TypeScript usados para dados do backend 2. Leia os services que fornecem esses dados 3. Compare os tipos TS com o schema real do banco (verifique em src/integrations/supabase/types.ts) 4. Se usa edge functions: compare o response type no frontend com o que a function realmente retorna PASSO 2 — INVESTIGAR: 1. TYPE MISMATCHES (frontend vs banco): - Campo marcado como required no tipo TS mas nullable no banco → crash quando null chega - Campo marked optional no tipo TS mas NOT NULL no banco → insert/update falha - Enum no frontend que não bate com check constraint do banco → valor rejeitado - Campo numérico no tipo mas string no banco (ou vice-versa) → comparações erradas - Date handling: frontend espera ISO string mas banco retorna timestamp com timezone 2. CONTRATOS DE API: - Edge function retorna campo que frontend não lê (dado perdido) - Frontend espera campo que edge function não retorna (undefined access) - Error response com formato diferente do que o frontend faz catch - Edge function mudou mas frontend ficou com contract antigo 3. REGRAS DO PROJETO QUE CAUSAM BUGS (leia .claude/rules/ para contexto, se existir; senão pule este item): - Uso de type="date" nativo em vez de DateInput → comportamento de data inconsistente, datas inválidas passam - Campos de evolução que não seguem a spec (peso sem min/max/step, textarea sem maxLength) → dados fora do range aceitos - RPCs proibidos chamados diretamente do frontend → bypass de segurança, possível erro de permissão - Formulário que não usa o sistema universal (formRegistry/validationRegistry) quando deveria → validação inconsistente 4. RACE CONDITIONS CROSS-LAYER: - Frontend faz 2 mutations concorrentes que conflitam no banco - Cache invalidation timing: query refetch antes da mutation completar no banco - Optimistic update no frontend + slow edge function → estado temporariamente inconsistente que o usuário vê COMO INVESTIGAR: 1. Abra src/integrations/supabase/types.ts e compare os tipos das tabelas envolvidas 2. Para cada campo usado no componente: verifique se nullable no banco 3. Grep por `type="date"` no componente e filhos 4. Grep por `supabase.rpc(` com funções da lista proibida 5. Compare o Zod schema (se usar forms) com o DB schema FORMATO DE SAÍDA (obrigatório): ## Contract & Integration Bugs: [ComponentName] ### Mismatches Encontrados Para cada: [Arquivo Frontend:Linha] vs [Tipo/Schema:Campo] | O que diverge | Impacto ### Regras Violadas que Causam Bugs Para cada: [Regra] | [Arquivo:Linha] | Bug resultante ### Race Conditions Cross-Layer Para cada: Cenário | Arquivos envolvidos | Impacto no usuário ### Suspeitos Para cada: O que pode divergir e em qual cenário ``` --- **Após os 3 agentes retornarem**, guarde os 3 outputs completos (copie o texto integral de cada retorno) e avance para a Fase 2. --- ## Fase 2 — Cross-Validator (Critic) 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 da Fase 1. ### Agente 4: Cross-Validator (Critic) ``` Você é o agente validador. Recebeu os relatórios de 3 bug hunters que analisaram o mesmo componente. Seu trabalho é: 1. REFUTAR: Para cada bug "confirmado", tente provar que NÃO é bug. Leia o código real nas linhas citadas e verifique se o bug realmente existe ou se o hunter errou. 2. DESCOBRIR: Ao cruzar os achados dos 3 hunters, procure bugs que NENHUM deles percebeu — bugs que só aparecem quando você olha a interação entre frontend, backend e contratos juntos. 3. CLASSIFICAR: Para cada bug que sobrevive à sua validação: - CRITICAL: crash, perda de dados, vazamento de dados entre usuários/tenants, bypass de segurança - HIGH: comportamento incorreto sem workaround, dados errados salvos - MEDIUM: erro com workaround ou que afeta edge case real - LOW: bug cosmético ou edge case muito improvável 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 (confirmados após re-verificação) Para cada: Severidade | [Arquivo:Linha] | Descrição | Validação: "Confirmei que X porque Y" ### Falsos Positivos (refutados) Para cada: Bug original | Por que não é bug: "O código está correto porque Z" ### Bugs Novos (descobertos no cruzamento) Para cada: Severidade | Descrição | 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 abaixo e substitua `[OUTPUT_AGENTE_4]` pelo texto integral do relatório 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. LISTA DE BUGS FINAL (ordenada por severidade, sem duplicatas): Formato tabela: | # | Severidade | Arquivo:Linha | Bug | Fix | 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 - Estimativa de complexidade: trivial / simples / requer cuidado 4. TESTES A ADICIONAR: - Para cada bug corrigido: teste que previne regressão - Cenário do teste + assertion esperada 5. RISCOS RESIDUAIS: - Bugs "suspeitos" que não foram confirmados mas merecem monitoramento - Áreas adjacentes que podem ser afetadas pelos fixes ``` --- ## Passo 4 — Apresentar e (se autorizado) executar o plano ### 4.1 — Apresentar ao usuário Mostre o relatório final do Agente 5 integralmente ao usuário. Não resuma mais — o Agente 5 já fez esse trabalho. ### 4.2 — Fixes de código (frontend/backend/edge functions) **Aguarde autorização** do usuário antes de aplicar qualquer fix de código, a menos que ele já tenha dito explicitamente "aplica os fixes" ou equivalente. Ao aplicar: - Siga a ordem exata do plano (dependências importam) - Um commit por fix (ou por grupo coeso de fixes relacionados) - Nunca commitar direto em `main` — seguir o workflow do CLAUDE.md: branch → commit → PR ### 4.3 — Mudanças de banco de dados (REGRA ESPECIAL) Se o plano de correção inclui qualquer mudança de banco (nova tabela, coluna, constraint, index, RLS policy, RPC, 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. **Procedimento obrigatório:** 1. **Classifique a mudança:** - **Aditiva (baixo risco):** CREATE TABLE/INDEX/POLICY novo, ADD COLUMN nullable, novo RPC - **Destrutiva (alto risco):** DROP, ALTER TYPE, RENAME, mudança em RLS existente, ADD COLUMN NOT NULL sem default, UPDATE em massa 2. **Valide a proposta contra boas práticas**, invocando via Skill: - `supabase-postgres-best-practices` — padrões de schema, índices, RLS, performance - Se necessário, consulte `search_docs` do MCP Supabase para dúvidas específicas 3. **Corrija a proposta se necessário.** Exemplos comuns: - Adicionar RLS policies se a tabela vai ter user_id - Criar índices em colunas usadas em WHERE/JOIN/ORDER BY - Usar `IF NOT EXISTS` / `IF EXISTS` para idempotência - Usar tipos apropriados (ex: `uuid` para ids, `timestamptz` para datas com timezone) - Nunca editar migration já aplicada — sempre criar nova 4. **Crie o arquivo da migration** em `supabase/migrations/YYYYMMDDHHMMSS_descricao.sql`, mas **NÃO execute ainda**. 5. **Mostre o SQL ao usuario** 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 `src/integrations/supabase/types.ts`, avise que precisa regerar os tipos 6. **Aguarde autorização explícita** ("aplica", "manda", "ok"). Sem autorização não rode `run-migration`. Para destrutivas, não aceitar autorização genérica anterior — pergunte especificamente sobre essa migration. 7. **Aplicação:** branch + commit do SQL + PR. Migration só roda em produção depois do PR aprovado, igual qualquer mudança no projeto. --- ## Notas operacionais - **Paralelismo é obrigatório na Fase 1.** Spawnar os 3 agentes em mensagens separadas triplica o tempo sem ganho nenhum. - **Preserve outputs integralmente entre fases.** Não resuma os relatórios dos bug hunters antes de passar pro Cross-Validator — ele precisa dos detalhes originais (arquivos, linhas, fixes sugeridos) pra validar. - **Se o componente é muito pequeno ou trivial** (ex: componente puramente visual sem lógica/estado/queries), avise o usuário que o pipeline pode ser overkill e ofereça uma análise mais leve em vez de rodar 5 agentes. - **Se um dos 3 hunters da Fase 1 não achar nada**, ainda assim avance para a Fase 2 — o Cross-Validator pode encontrar bugs no cruzamento mesmo com hunters "vazios".