O que Invertebrate — Revisão estilo Greptile faz?
A vantagem do Greptile sobre um linter é o contexto: ele revisa o diff contra um grafo de todo o repositório, então captura a renomeação que deixou três chamadores quebrados, o novo endpoint sem o decorador de autenticação que todo irmão possui, a "otimização" que torna um chamador um no-op. Reproduza isso. Uma revisão que apenas lê o diff não é esta skill.
Sua segunda vantagem é o sinal: cada comentário é um bug verificado e concreto com uma correção, não um ensaio de estilo. Equipes desativam revisores que gritam "lobo". Na dúvida, deixe de fora.
1. Resolver o alvo
| O que o usuário forneceu | Fonte do diff |
|---|---|
| Número/URL do PR | gh pr view <n> --json title,body,baseRefName,headRefName,files + gh pr diff <n> |
| Branch | git diff <base>...HEAD (três pontos = diff a partir da base de merge; base = main/master/develop, o que existir) |
| Nada | git diff HEAD (staged+unstaged); se vazio, a branch atual vs sua base |
Um arquivo .diff/.patch | esse arquivo; a árvore de trabalho é o repositório pós-alteração |
Leia o título/descrição do PR se disponível (do gh, ou de um arquivo de descrição fornecido pelo usuário). "Um PR de segurança é enviado sem a correção" é uma captura real do Greptile: liste cada afirmação que a descrição faz ("corrige X", "adiciona validação para Y") e verifique se o diff realmente entrega. Uma correção reivindicada que não está no diff é uma descoberta com a gravidade do bug que ela afirma corrigir.
Um PR limpo é um resultado válido. Se a verificação não encontrar descobertas, diga isso, pontue 4-5/5 e pare — inventar problemas para parecer minucioso é a maneira mais rápida de ter um revisor silenciado.
2. Carregar configuração de revisão
A pasta de configuração é .invertebrate/. Para compatibilidade com equipes que já usam Greptile, .greptile/ usa o formato idêntico e é lida onde não existir .invertebrate/. Resolva por diretório: em cada diretório, .invertebrate/ se presente, senão .greptile/ — nunca ambos de um mesmo diretório. Verifique a raiz do repositório e todos os diretórios que contêm um arquivo alterado (monorepo: o mais próximo vence para configurações escalares, listas/instruções acumulam dos pais). Também aceite um greptile.json legado na raiz com os mesmos campos. Nunca crie ou modifique essas pastas — são entrada somente leitura.
config.json:strictness1|2|3 (padrão 2) — veja filtragem na §5commentTypes(padrão["logic","syntax","style"]) — remove descobertas de tipos não listadosignorePatterns(sintaxe gitignore, separados por nova linha) — pula arquivos correspondentesinstructions— orientação livre para o revisor, siga-arules[]—{id, rule, scope[glob], severity: low|medium|high, enabled}; aplique apenas ondescopecorresponder;disabledRulesremove ids herdados
rules.md— regras markdown simples para aquela árvore de diretóriofiles.json—{files:[{path, description, scope}]}: leia esses arquivos como contexto quando o escopo corresponder (ou sempre se não houver escopo)
Nenhuma dessas pastas em lugar algum? Use os padrões de codificação de CLAUDE.md / AGENTS.md / CONTRIBUTING.md como regras. Anote no relatório qual configuração foi aplicada.
Uma violação de regra se torna uma descoberta que cita a regra (Rule: <id ou primeiras palavras>). A gravidade da regra mapeia: high→P1, medium→P2, low→P2.
3. Construir o grafo de contexto (a parte que importa)
Para cada hunk alterado, identifique os símbolos que ele define, remove, renomeia ou altera a assinatura/semântica de (funções, métodos, classes, tipos, constantes exportadas, rotas, colunas de BD, chaves de configuração, variáveis de ambiente, nomes de eventos).
Para cada um desses símbolos, pesquise o repositório inteiro, não apenas arquivos alterados:
- Chamadores / referências —
Greppara o nome antigo e o novo. Um símbolo removido/renomeado com referências sobreviventes é um bug garantido. - Irmãos — código que faz o mesmo tipo de coisa (outros endpoints no roteador, outros manipuladores da mesma interface, outras migrações). Código novo que pula um padrão que todo irmão segue (decorador de autenticação, log de auditoria, validação, transação, trava,
await) é uma das principais capturas do Greptile. - Chamados — leia a implementação de qualquer coisa que o novo código chame e cujo contrato importe (lança exceção? retorna null? já faz lock? é assíncrono?).
- Fluxo de dados — de onde vêm as entradas (controladas pelo usuário? parâmetro de URL?) e para onde vão (SQL/HogQL, shell, caminho de sistema de arquivos, execução de código dinâmico, HTML).
Mantenha uma lista curta: símbolo → arquivos que dependem dele → o que a mudança faz com eles. Use-a para escrever descobertas; não a despeje no relatório.
4. Caçar
Percorra o diff com o grafo em mãos. Categorias que o Greptile realmente reporta, com exemplos reais:
- Lógica — loop termina cedo deixando estado parcial; flag/condição invertida; valor escapado de uma verificação; avisos nunca chegam ao usuário.
- Refatoração — renomeação deixa chamadores indefinidos; código movido perde um efeito colateral.
- Segurança — falta de autenticação/autorização em novo endpoint; injeção via entrada do usuário em consulta/shell/caminho; fuga de sandbox/escopo (symlinks, montagens,
~, expansão de variáveis); campo nulo/ausente burla um guarda. - Validação — entrada vazia/malformada aceita como válida; entrada válida rejeitada; regex não ancorada.
- Runtime / Sintaxe — chamada para método indefinido; falta de
await; número errado de argumentos; incompatibilidade de tipo; código que não compila. - Tratamento de erros — exceções engolidas; tracebacks/segregados brutos vazados para clientes; recurso fechado em handle errado/indefinido no caminho de erro.
- Concorrência — corridas de verificação-depois-ação e leitura-modificação-escrita; estado mutável compartilhado entre tarefas/threads; ordenação de inicialização perde eventos.
- Perda / integridade de dados — escritas não atômicas; dupla aplicação em repetição; truncamento silencioso; dados deletados reaparecendo.
- Desempenho — consultas N+1, O(n²) em caminho crítico, uma "otimização" que é um no-op silencioso.
- Alinhamento / vazamento — verdade básica ou segredos expostos por um endpoint de estado/depuração ou log.
Verifique cada candidato antes de mantê-lo. Você deve ser capaz de afirmar: a linha exata, a entrada/estado concreto que o aciona e o resultado errado. Se não conseguir construir a falha, descarte-a. Releia o código ao redor — metade dos bugs aparentemente plausíveis são tratados três linhas depois.
5. Classificar e filtrar
Cada descoberta recebe:
- Gravidade — P0 deve corrigir antes do merge (falha de segurança, perda de dados, crash em caminho comum, quebra de build). P1 deve corrigir (comportamento errado, caso de borda quebrado, violação de regra com gravidade alta). P2 considerar (manutenibilidade, desempenho menor, regra de baixa gravidade).
- Tipo —
logic(bugs, comportamento, casos de borda),syntax(não compila/executa, uso incorreto da linguagem),style(qualidade, nomeação, convenções).
Filtrar por strictness:
- 1 — mantenha P0, P1, P2.
- 2 (padrão) — mantenha P0, P1; mantenha P2 apenas se violar uma regra explícita configurada.
- 3 — mantenha P0, mais estes P1s: segurança, crashes/500s alcançáveis a partir de entrada do usuário e violações de regras configuradas com gravidade
high. Strictness 3 significa "apenas o que chamaria alguém ou o que a equipe explicitamente pediu", e um crash acionável remotamente se qualifica.
Em seguida, remova tipos não presentes em commentTypes. Formatação pura que um formatador corrigiria: nunca reporte.
6. Pontuação de confiança (0-5)
| Pontuação | Significado |
|---|---|
| 5/5 | Pronto para produção — merge |
| 4/5 | Pequenos ajustes — merge após correções menores (apenas P2s) |
| 3/5 | Problemas de implementação — abordar feedback primeiro (qualquer P1) |
| 2/5 | Bugs significativos — precisa de retrabalho (múltiplos P1s, ou um P0 fácil de corrigir) |
| 0-1/5 | Problemas críticos — repensar (P0 de segurança/perda de dados, ou design está errado) |
As pontuações são contextuais: o mesmo bug em pagamentos/auth/migrations pontua mais baixo do que em um script interno. Dê uma frase de justificativa.
7. Diagrama
Escolha com base no que mudou; pule para diffs triviais (documentação, alterações de configuração, <~20 linhas de lógica local):
- sequenceDiagram — interações de múltiplos componentes, fluxos de API/requisição, ordenação assíncrona/concorrente (mostre a condição de corrida se houver)
- erDiagram — alterações de esquema / modelo de dados
- classDiagram — alterações de hierarquia de classe/interface
- flowchart — alterações de fluxo de controle / lógica de negócios
Diagrame a mudança, não o sistema inteiro. Mantenha com menos de ~15 nós. Marque o passo problemático com um Note / rótulo.
8. Saída
Use exatamente esta estrutura (seções podem ser omitidas apenas onde indicado):
## Revisão Invertebrate — <título do PR ou branch>
### Resumo
<2-4 frases, linguagem natural: o que a mudança faz, quem/o que afeta, por quê. Em seguida, 1 frase sobre o principal risco.>
### Pontuação de Confiança: N/5
<uma frase explicando por quê>
### Descobertas
| # | Sev | Tipo | Localização | Problema |
|---|---|---|---|---|
| 1 | P0 | logic | `caminho/arquivo.ts:42` | <título curto> |
(Se nenhuma: "Nenhum problema encontrado.")
### Diagrama
```mermaid
...
(omitir seção para alterações triviais)
Comentários Inline
1. [P0 · logic] <título curto>
caminho/arquivo.ts:42
<O que está errado, o cenário de falha concreto e — se entre arquivos — quais outros arquivos quebram e por quê. 2-5 frases.>
- linha antiga
+ linha corrigida
2. ...
arquivos revisados · config: <caminho .invertebrate ou .greptile | CLAUDE.md | padrões> · strictness ·
Diffs de sugestão de correção devem ser reais, mínimos e aplicáveis ao código real. Se a correção abranger vários arquivos, mostre o hunk de cada arquivo com seu caminho como linha de cabeçalho. Se não existir uma correção segura em um único hunk, descreva-a em vez de inventar uma.
Após o relatório, ofereça: "Diga `fix all`, `fix P0` ou `fix #2` e eu os aplicarei." Não aplique correções sem solicitação.
## 9. Postar no GitHub (apenas quando solicitado: `--post`, "post it", "comment on the PR")
Postar é voltado para o exterior — faça isso apenas mediante solicitação explícita para aquele PR.
1. Obtenha `owner/repo` (`gh repo view --json nameWithOwner -q .nameWithOwner`) e o sha do head (`gh pr view <n> --json headRefOid -q .headRefOid`).
2. Comentários inline só podem mirar linhas presentes no diff do PR (lado DIREITO, números de linha novos). Descobertas em linhas fora do diff vão apenas no corpo do resumo.
3. Escreva o JSON da revisão em um arquivo temporário e poste-o em uma única chamada:
```json
{
"commit_id": "<sha do head>",
"event": "COMMENT",
"body": "<o relatório markdown completo da §8 menos a seção Comentários Inline>",
"comments": [
{"path": "src/arquivo.ts", "line": 42, "side": "RIGHT",
"body": "**P0 · logic** — <título>\n\n<explicação>\n\n```suggestion\n<substituição para exatamente a linha 42>\n```"}
]
}
gh api repos/<proprietário>/<repositório>/pulls/<n>/reviews --method POST --input review.json
Use blocos suggestion do GitHub apenas quando a substituição cobrir exatamente a(s) linha(s) comentada(s) (use `start_line` + `line` para múltiplas linhas). Caso contrário, use um bloco diff. Nunca use REQUEST_CHANGES/APPROVE a menos que o usuário peça. Relate a URL da revisão da resposta.