pedro-oscar/shorts-ai

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

• Padrões: o código segue os padrões de codificação documentados deste repositório?
• Especificação: o código implementa fielmente a issue/especificação original?

Ambos os eixos são executados 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, informe ao usuário para executar /setup-matt-pocock-skills.

Processo

1. Fixar o ponto fixo

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

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

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

2. Identificar a fonte da especificação

Procure pela especificação original, nesta ordem:

1. Referências a issues nas mensagens de commit (#123, Closes #45, GitLab !67, etc.), obtidas através do 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 da branch ou funcionalidade.
4. Se nada for encontrado, pergunte ao usuário onde está a especificação. Se ele disser que não existe, o subagente de Especificação será ignorado e relatará "nenhuma especificação disponível".

3. Identificar as fontes de padrões

Pesquise no repositório por todo arquivo que documente como o código deve ser escrito. Quando CODIGO_PADROES.md ou CONTRIBUTING.md existir, ele deve estar na lista.

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

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

Cada cheiro lê o que é → como corrigir; corresponda-o ao diff:

• Nome Misterioso: uma função, variável ou tipo cujo nome não revela o que faz ou contém. → renomeie-o; se nenhum nome honesto surgir, o design é nebuloso.
• Código Duplicado: a mesma forma lógica aparece em mais de um trecho ou arquivo na alteração. → extraia a forma compartilhada, chame-a de ambos.
• Inveja de Característica: um método que acessa dados de outro objeto mais do que os seus próprios. → mova o método para os dados que ele inveja.
• Agrupamentos de Dados: os mesmos poucos campos ou parâmetros viajam juntos repetidamente (um tipo querendo nascer). → agrupe-os em um tipo, passe esse.
• Obsessão por Primitivos: 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: o mesmo switch/if-cascata no mesmo tipo recorre pela alteração. → substitua por polimorfismo, ou um mapa compartilhado por ambos os locais.
• Cirurgia de Espingarda: uma mudança lógica força edições espalhadas em muitos arquivos no diff. → reúna o que muda junto em um módulo.
• Mudança Divergente: 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: abstração, parâmetros ou ganchos adicionados para necessidades que a especificação não tem. → delete-os; reencurve até que uma necessidade real apareça.
• Cadeias de Mensagens: longa navegação a.b().c().d() da qual o chamador não deveria depender. → esconda o percurso em um método no primeiro objeto.
• Homem do Meio: uma classe ou função que principalmente apenas delega adiante. → corte-a, chame o destino real diretamente.
• Recusa de Herança: 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

Emita ambas as chamadas de subagentes juntas, em primeiro plano, e agregue os relatórios que eles retornarem.

Prompt do subagente Padrões deve incluir:

• O comando diff completo e a lista de commits.
• A lista de arquivos-fonte de padrões que você encontrou no passo 3, mais a linha de base de cheiros do passo 3 colada na íntegra (o subagente não tem outro acesso a ela).
• A instrução: "Relate, por arquivo/trecho quando 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 ferramentas enforce. Abaixo de 400 palavras."

Prompt do subagente Especificação deve incluir:

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

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

5. Agregar

Apresente os dois relatórios sob os cabeçalhos ## Padrões e ## Especificação, na íntegra 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 único entre os eixos: isso é a reordenação que a separação visa prevenir.

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, Especificação reprovado.
• Código que faz exatamente o que a issue pediu mas quebra as convenções do projeto → Especificação aprovado, Padrões reprovado.

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