Razsk/VideoStudio

Revisão em dois eixos do diff entre HEAD e um ponto fixo fornecido pelo usuário:

• Padrões: o código está em conformidade com os padrões de codificação documentados deste repositório?
• Especificação (Spec): o código implementa fielmente a issue/especificação original?

Ambos os eixos executam como subagentes paralelos para que não poluam o contexto um do outro. Em seguida, esta skill agrega os resultados.

O rastreador de issues deve ter sido fornecido a você. Caso contrário, diga ao usuário para executar /setup-matt-pocock-skills.

Processo

1. Definir o ponto fixo

Qualquer que seja o ponto fixo informado pelo usuário (um SHA de commit, nome de branch, tag, main, HEAD~5, etc.). Se ele não especificou um, pergunte.

Capture o comando diff uma vez: git diff <ponto-fixo>...HEAD (três pontos, para que a comparação seja contra o merge-base). Observe também a lista de commits via git log <ponto-fixo>..HEAD --oneline.

Antes de prosseguir, confirme se o ponto fixo é resolvível (git rev-parse <ponto-fixo>) e se o diff não está vazio. Uma referência inválida ou diff vazio deve falhar aqui, não dentro dos dois subagentes paralelos.

2. Identificar a fonte da especificação

Procure a especificação original, nesta ordem:

1. Referências a issues nas mensagens de commit (#123, Closes #45, GitLab !67, etc.), obtidas via o fluxo de trabalho no documento do rastreador.
2. Um caminho passado pelo usuário como argumento.
3. Um arquivo de especificação em docs/, specs/ ou .scratch/ que corresponda ao nome do branch ou funcionalidade.
4. Se nada for encontrado, pergunte ao usuário onde está a especificação. Se ele disser que não há, o subagente Spec pulará e relatará "nenhuma especificação disponível".

3. Identificar as fontes de padrões

Pesquise no repositório todos os arquivos que documentam como o código deve ser escrito. Quando CODING_STANDARDS.md ou CONTRIBUTING.md existir, eles devem estar na lista.

Além do que o repositório documenta, o eixo de Padrões sempre carrega a linha de base de cheiros de código abaixo: um conjunto fixo de code smells de Fowler (Refactoring, cap. 3) que se aplica mesmo quando o repositório não documenta nada. Duas regras o vinculam:

• O repositório substitui. Um padrão documentado do repositório sempre vence; onde ele endossa algo que a linha de base sinalizaria, suprima o cheiro.
• Sempre um julgamento. Cada cheiro é uma heurística rotulada ("possível Feature Envy"), nunca uma violação rígida. Como qualquer padrão aqui, ignore qualquer coisa que as ferramentas já imponham.

Cada cheiro descreve o que é → como corrigir; compare com o diff:

• Nome Misterioso (Mysterious Name): uma função, variável ou tipo cujo nome não revela o que faz ou armazena. → renomeie; se nenhum nome honesto vier, o design está confuso.
• Código Duplicado (Duplicated Code): a mesma estrutura lógica aparece em mais de um trecho ou arquivo na alteração. → extraia a estrutura compartilhada, chame-a de ambos os lugares.
• Inveja de Recursos (Feature Envy): um método que acessa dados de outro objeto mais do que os seus próprios. → mova o método para o objeto que ele inveja.
• Grupinhos de Dados (Data Clumps): os mesmos poucos campos ou parâmetros continuam viajando juntos (um tipo querendo nascer). → agrupe-os em um tipo, passe-o.
• Obsessão por Primitivos (Primitive Obsession): um primitivo ou string representando um conceito de domínio que merece seu próprio tipo. → dê ao conceito seu próprio tipo pequeno.
• Switches Repetidos (Repeated Switches): o mesmo switch/cascata de if no mesmo tipo aparece repetidamente na alteração. → substitua por polimorfismo ou um mapa compartilhado.
• Cirurgia com Espingarda (Shotgun Surgery): uma mudança lógica força edições dispersas em muitos arquivos no diff. → reúna as mudanças em um único módulo.
• Mudança Divergente (Divergent Change): um arquivo ou módulo é editado por várias razões não relacionadas. → divida para que cada módulo mude por uma razão.
• Generalidade Especulativa (Speculative Generality): abstração, parâmetros ou ganchos adicionados para necessidades que a especificação não tem. → exclua-os; encurte até que uma necessidade real apareça.
• Cadeias de Mensagens (Message Chains): longa navegação a.b().c().d() da qual o chamador não deveria depender. → esconda a caminhada atrás de um método no primeiro objeto.
• Homem do Meio (Middle Man): uma classe ou função que principalmente delega para a frente. → corte-o, chame o alvo real diretamente.
• Herança Recusada (Refused Bequest): uma subclasse ou implementador que ignora ou sobrescreve a maior parte do que herda. → abandone a herança, use composição.

4. Gerar ambos os subagentes em paralelo

Dispare ambas as chamadas de subagente juntas, em primeiro plano, e agregue os relatórios que retornarem.

Prompt do subagente de Padrões deve incluir:

• O comando diff completo e a lista de commits.
• A lista de arquivos-fonte de padrões que você encontrou na etapa 3, mais a linha de base de cheiros da etapa 3 transcrita por completo (o subagente não tem outro acesso a ela).
• A instrução: "Relate, por arquivo/trecho onde relevante: (a) todo lugar onde o diff viola um padrão documentado: cite o padrão (arquivo + a regra); e (b) qualquer cheiro da linha de base que você identificar: nomeie-o e cite o trecho. Diferencie violações rígidas de julgamentos: violações de padrões documentados podem ser rígidas, mas cheiros da linha de base são sempre julgamentos, e um padrão documentado do repositório substitui a linha de base. Pule qualquer coisa que as ferramentas já imponham. Abaixo de 400 palavras."

Prompt do subagente de Spec deve incluir:

• O comando diff e a lista de commits.
• O caminho ou o conteúdo obtido da especificação.
• A instrução: "Relate: (a) requisitos que a especificação pediu e estão ausentes ou parciais; (b) comportamento no diff que não foi solicitado (escopo extra); (c) requisitos que parecem implementados mas cuja implementação parece errada. Cite a linha da especificação para cada descoberta. Abaixo de 400 palavras."

Se a especificação estiver faltando, pule o subagente Spec e anote isso no relatório final.

5. Agregar

Apresente os dois relatórios sob os cabeçalhos ## Padrões e ## Especificação, ipsis litteris ou levemente limpos. Não mescle ou reordene os achados, pois os dois eixos são deliberadamente separados (veja Por que dois eixos).

Termine com um resumo de uma linha: total de achados por eixo e o pior problema dentro de cada eixo (se houver). Não escolha um vencedor entre os eixos: isso é a reordenação que a separação existe para evitar.

Por que dois eixos

Uma alteração pode passar em um eixo e falhar no outro:

• Código que segue todos os padrões mas implementa a coisa errada → Padrões aprovado, Spec reprovado.
• Código que faz exatamente o que a issue pediu mas quebra as convenções do projeto → Spec aprovado, Padrões reprovado.

Relatá-los separadamente impede que um eixo mascare o outro.