vibe-review

Imported from korflux/vibeflow (vibe-review/SKILL.md). Install upstream with npx skills add korflux/vibeflow --skill vibe-review. Copyright stays with the author.

vibe-review

Não invente n se há plan. Não edite source, teste nem lockfile. Sem review.md não há veredito. Um arquivo por alvo. Sem .vibeflow/: /vibe-init. Open Questions no arquivo = defeito. Correções ficam na vibe-implement; o Git só é finalizado após Approve e confirmação humana. Decisões vigentes em REGRAS.md só são sincronizadas após Approve sem bloqueios e confirmação humana explícita. Recomende iniciar a review em um chat novo, separado da implementação. Se o humano preferir o chat atual, prossiga sem bloquear.

A investigação começa pela pergunta de auditoria e pelo T*/diff que precisa ser provado. Use rg --files para localizar os artefatos, paths alterados, testes e referências aplicáveis; use rg -n para localizar símbolos, contratos e evidências. Abra somente as entradas e dependências do fluxo real e expanda a leitura quando uma lacuna bloquear o veredito. O inventário é mapa de seleção, não autorização para ler a árvore inteira.

0. Entender e usar o script

1. Resolva o diretório desta skill e leia o motor que vai executar. Entenda alvo, cadeia exigida, recusas, preparação do destino e preservação do arquivo vivo. Confirme que ele não escreve REGRAS.md; corrija e prove qualquer defeito antes de seguir.
2. No cwd do repo:
   • Windows: pwsh "<skill>/scripts/review.ps1"
   • Unix: bash "<skill>/scripts/review.sh" (Python 3, senão pwsh 7)
   • Alvo MVP: acrescente -Mvp ou --mvp.
3. Leia o JSON operacional emitido no stdout pelo comando acima. Use rg --files e rg -n para localizar o alvo, o que files listar, plan.md com status, dependências, bloqueios, paths e provas de cada T*, spec.md, analyze.md se houver, REGRAS.md e o diff apontado pelo humano ou da sessão. Abra somente os paths que sustentam o veredito; não leia a árvore inteira.

INIT_AUSENTE exige init. REVIEW_SEM_ALVO, REVIEW_CADEIA_INCOMPLETA, MVP_INESPERADO, MODO_INVALIDO, FASE_AUSENTE e SLUG_INVALIDO não são contornados.

Apply:

• first-pass reuse/atualizar: pwsh "<skill>/scripts/review.ps1" -Apply (--dir se o alvo errar)
• avulsa sem cadeia: … -Apply -Slug "<frase curta>"
• MVP: … -Apply -Mvp, sem slug ou dir
• Unix: review.sh --apply / --apply --slug "…"

1. Abrir (7 linhas)

rota · tipo · alvo · plan/fila · spec · analyze · diff · chat

final · etapa 1 first-pass · alvo: phase-2-vibe-review · fila: concluída · spec: sim · analyze: sim · diff: working tree · chat: novo recomendado

modo_sugerido=criar e sem --slug = não há pasta. Não grude review nova no N de outro pedido. Já existe review.md = próxima etapa no mesmo arquivo.

2. Gate

Q: <só se o veredito depende do humano>
RECOMENDO: <opção>, <1 linha>
(ok / outra?)

Barra de Approve: saúde do código + convenção do repo. Não bloquear gosto. No Express, julgue rastreabilidade e inspecione o resultado renderizado somente quando ele fizer parte do aceite; cubra a acessibilidade afetada pela mudança. Segurança e banco só abrem se o diff tocar essas superfícies.

3. Checkpoint, review final e prova proporcional

A review é um processo cético e investigativo. Não confie cegamente em checkboxes nem em logs passados. Escolha o tipo pela fila e pelo checkpoint explícito do plan.md; não transforme uma revisão parcial em veredito de fase.

Selecionar e executar provas

1. Use o plan.md como registro das execuções: confira o status da T*, Deps e bloqueios, Arquivos e Prova/Verificação. Compare os inputs da prova com o estado integrado e reaproveite prova verde somente quando esses inputs permanecem iguais e a prova ainda cobre a integração. Mudança em plan, spec ou review não invalida prova de código; edição posterior em código/teste invalida somente a prova afetada. implement.md histórico não é necessário para a review.
2. Execute somente a menor prova que falta para julgar o marco ou a integração. Reexecute uma prova quando estiver ausente, falhou, ficou desatualizada por edição posterior, não cobre a integração entre tasks, ou quando um risco alterado exigir cobertura adicional.
3. Não rode automaticamente a matriz de comandos de cada T*. Na review final, prefira uma verificação agregada existente quando ela comprovar a integração; rode o Smoke Test somente quando a entrada real tiver mudado, sua prova estiver ausente/desatualizada ou for necessária para cobrir o fluxo integrado.
4. Registre em cada etapa as provas reaproveitadas, os comandos executados e o motivo. Se uma prova necessária falhar, abra R* Required com comando e remédio; não aprove silenciosamente.

Inspecione o código integrado e aplique estes pilares ao escopo da etapa:

1. Rastreabilidade e Verificação Anti-Alucinação (Audit Trail):
   • Cruze o pedido (interview.md quando houver), a Cobertura da origem da spec, os critérios A*/C* e o plan.md. No checkpoint, julgue só o marco declarado; no final, confirme que as tasks concluídas produziram a integração pedida. Item aplicável da interview sem destino na spec é lacuna de escopo, inclusive em rota sem analyze.
   • Inspecione os paths e o fluxo real que comprovam esse escopo. T* marcada sem código correspondente vira R* gap: missing (Critical).
2. Provas e Integridade dos Testes:
   • Cace falsos positivos: testes sem asserções reais, testes que dão assert True, testes que apenas testam mocks sem exercitar a implementação real.
   • Se a task consolidou testes da capacidade alterada, confira se os cenários e afirmações removidos continuam cobertos por provas executáveis. Duplicação remanescente só vira achado quando causa custo material ou mascara uma lacuna; não peça limpeza ampla fora da entrega.
   • Verifique casos de borda e caminhos de erro relevantes às superfícies alteradas. Use a seleção de provas acima; não repita suites de T* sem lacuna ou risco que o justifique.
   • Se uma prova necessária falhar ou for falso positivo: registre R* Required.
3. Auditoria Implacável de Segurança e Hardening:
   • Nas superfícies tocadas pelo diff, inspecione entradas externas, formulários, parâmetros de URL e bodies de request (references/security-and-hardening.md):
     • Há risco de Injeção (SQL, XSS, Command/Shell Injection, SSRF)?
     • Há limite de caracteres e tamanho de payload para prevenir DoS e travamentos?
     • IDOR: o servidor valida se o usuário autenticado tem permissão sobre o recurso manipulado?
     • Há segredos, chaves ou tokens expostos no código, no bundle do frontend ou gravados em logs?
   • Toda brecha explorável vira R* Critical. Falta de limite/validação de borda vira R* Required.
4. Inspeção Visual e Interface:
   • Inspecione no navegador quando Visual: necessária estiver no plan ou quando o diff revelar uma saída renderizada relevante não prevista. Tocar arquivo de UI, HTML ou DOM não basta. Se Visual: dispensada estiver justificada por prova executável e o diff confirmar que não há resultado renderizado a julgar, não abra o navegador.
   • Reaproveite a evidência visual registrada pela implement quando seus inputs continuam válidos e ela cobre a integração. Só execute ou repita navegador se a prova estiver ausente/desatualizada, faltar cobertura da integração, ou o risco/diff exigir outro estado ou viewport. Quando necessário, selecione nesta ordem conforme references/ui-visual-quality.md: navegador integrado (@Browser ou equivalente), MCP Server chrome-devtools, ou Playwright somente se já existir no repositório ou for solicitado para fluxos repetíveis e assertions.
   • Comece pela rota/tela, estado e viewport afetados pelo diff; amplie quando layout, responsividade, interação, componente compartilhado ou risco exigirem. Registre rota, viewport, estado, ações e evidência observada. Aplique a checklist da referência ao recorte afetado, incluindo acessibilidade e erros relevantes de runtime.
   • Para ações compactas, aceite icon-only somente quando a ação for universalmente reconhecível, como lixeira para apagar, com nome acessível, área de interação adequada, foco visível e tooltip quando aplicável. Ações ambíguas continuam com texto.
   • Se a prova renderizada for necessária e não houver capacidade ou evidência válida, abra R* Required; não aprove silenciosamente e não instale ferramenta automaticamente.
5. Simplificação e Qualidade de Código:
   • Inspecione se o código é o mínimo necessário (YAGNI, sem estruturas especulativas, sem duplicação de lógica ou componentes).
   • Verifique se todas as funções criadas ou modificadas possuem comentários semânticos obrigatórios.
   • Decisões críticas: cruze interview, spec, plan e analyze. Decisão desrespeitada ou conflito aberto bloqueia Approve.
6. Auditoria de Banco de Dados, Migrations e Precisão Numérica:
   • Se o diff tocar persistência ou valores numéricos/monetários (references/database-and-migrations.md):
     • Valores monetários, taxas ou cálculos exatos usam FLOAT/REAL em vez de DECIMAL/NUMERIC? Vira R* Critical.
     • Há queries com risco de SQL Injection ou interpolação não parametrizada? Vira R* Critical.
     • Há migrations destrutivas (DROP COLUMN, DROP TABLE) sem plano de rollback e autorização humana? Vira R* Critical.
     • Há colunas de Foreign Key sem índice explícito ou queries N+1 em loops? Vira R* Required.
     • Há SELECT * desnecessário em código de produção ou paginação por OFFSET massivo? Vira R* Required.

Finding: evidência (path) + severidade + remédio nomeado + prova. Sem evidência concreta não entra. Achado novo = próximo R* livre. Não renumerar fechados.

Remédio aponta vibe-implement + o que fazer. Esta skill não aplica código.

4. Escrever e salvar já

Molde: templates/review.md. Uma casa por fato. Omita seção que esta etapa não precisa.

Status: rascunho durante checkpoints e enquanto o veredito final aguarda confirmação; request-changes enquanto houver R* bloqueante em [ ]; aprovado somente após Approve final, fila concluída e confirmação humana.

Não pergunte se pode salvar. Não cole o corpo no chat.

Etapa 1 (não há review.md): execute o apply para preparar o review.md vivo e escreva nele diretamente (§0). Registre o tipo e o escopo antes de julgar.

Etapa 2+ (já há review.md): edite o vivo diretamente. Acrescente ### Etapa N e atualize checklist e provas sem substituir o histórico. Só a review final atualiza o veredito vigente para Approve; checkpoint registra o resultado do marco na própria etapa.

Resposta no chat

Responda, só:

Review gravada: <created.path>/review.md

- Etapa: <N> · Tipo: checkpoint | final · Resultado: Marco aprovado | Request changes | Approve final | Approve com defer
- Fila: <T* restantes | concluída>
- Abriu: <R* ou nenhum>
- Fechou: <R* ou nenhum>
- Handoff: vibe-implement | volta vibe-spec | finalização Git da phase
- Chat: review recomendada em conversa separada da implementação; para correções, novo chat também é recomendado. A continuidade é livre.

Arquivo disponível em <created.path>/review.md. Em checkpoint, a fase continua aberta; na review final, responda "aprovado" para sincronizar decisões e encerrar, ou indique os ajustes desejados.

5. Fechar

Commitável: o review.md vivo e, somente no fechamento final aprovado, os artefatos residuais autorizados da phase. Checkpoint não cria commit residual nem publica a phase. Request changes → handoff vibe-implement (arquivo + R* em [ ]), com recomendação de novo chat para a correção. Se o usuário pedir para corrigir imediatamente, inicie vibe-implement; se preferir permanecer neste chat, prossiga sem bloquear. O review.md e o diff são a ponte. Approve final sem R* bloqueantes em [ ] ainda é proposta até o humano ler e confirmar.

Após aprovação humana explícita da review final, com a fila concluída:

1. Marque # Status: aprovado, o veredito Approve e a aprovação humana no review.md vivo.
2. Se Decisões para vigência estiver vazia, feche a cadeia sem tocar regras.
3. Se houver linhas, aplique patch mínimo em .vibeflow/REGRAS.md. Crie ou atualize uma única seção ## Decisões vigentes com tabela ID | Decisão vigente | Fonte. Atualize por ID, preserve linhas não citadas e use como fonte o review aprovado do alvo.
4. Não copie justificativa, histórico ou impacto para as regras. Eles permanecem nos artefatos.
5. Releia REGRAS.md e confirme que apenas os IDs aprovados mudaram. Review rascunho, Request changes ou Approve sem confirmação humana nunca autoriza sync.

Finalização Git da phase

Esta seção só se aplica à review final, depois da aprovação humana explícita, com todas as T* concluídas e sem Critical ou Required em [ ]. Checkpoint nunca abre finalização Git.

1. Execute a prova final necessária para a integração conforme §3, sem repetir automaticamente a matriz de cada T*. Execute git diff --check e gitleaks quando previsto pelo repositório.
2. Compare o estado atual com o snapshot da review. Se houver path fora da phase, das decisões aprovadas ou da correção registrada, pare e peça isolamento; não misture trabalho pré-existente.
3. Adicione somente os paths residuais autorizados, com git add -- path/da/phase .vibeflow/REGRAS.md quando a sincronização foi aprovada. Nunca use git add -A ou git add ..
4. Valide git diff --cached --check e a lista de paths. Crie chore(phase-N): finalize review sem Co-Authored-By quando houver mudanças residuais. Não crie commit vazio; se não houver residual, o último commit da task é o HEAD da phase.
5. Execute git push para o upstream do branch atual, sem --force. Ausência de upstream, falha de commit ou falha de push mantém o handoff bloqueado e precisa ser informada com a causa segura.
6. Registre no review.md e no chat o hash do commit final ou o HEAD já existente, o resultado do push e os paths enviados. O inventário é JSON transitório no stdout.