Castle-Solutions/landing

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: 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 suas descobertas.

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 SHA de commit, nome de branch, tag, main, HEAD~5, etc.). Se não foi especificado, peça-o.

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

Antes de prosseguir, confirme que o ponto fixo é válido (git rev-parse <ponto-fixo>) e que 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 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 há, o subagente de Especificação irá 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 Padrões sempre carrega a linha de base de smells 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 se sobrepõe. Um padrão documentado do repositório sempre vence; onde ele endossa algo que a linha de base sinalizaria, suprima o smell.
• Sempre um julgamento. Cada smell é uma heurística rotulada ("possível Feature Envy"), nunca uma violação definitiva. Como qualquer padrão aqui, pule o que ferramentas já impõem.

Cada smell descreve o que é → como corrigir; compare com o 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 vier, o design está obscuro.
• Código Duplicado: a mesma estrutura lógica aparece em mais de um trecho ou arquivo na alteração. → extraia a estrutura compartilhada e chame-a de ambos os lugares.
• Inveja de Características: um método que acessa mais os dados de outro objeto do que os seus próprios. → mova o método para o objeto que ele inveja.
• Aglomerados de Dados: os mesmos poucos campos ou parâmetros andam juntos repetidamente (um tipo querendo nascer). → agrupe-os em um tipo e passe-o.
• 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 aparece repetidamente na alteração. → substitua por polimorfismo ou um mapa que ambos os locais compartilhem.
• Cirurgia com Espingarda: uma única mudança lógica força edições espalhadas por muitos arquivos no diff. → reúna o que muda junto em um único módulo.
• Mudança Divergente: um arquivo ou módulo é editado por vários motivos não relacionados. → divida para que cada módulo mude por um motivo.
• Generalidade Especulativa: abstrações, parâmetros ou ganchos adicionados para necessidades que a especificação não tem. → remova-os; simplifique até que uma necessidade real apareça.
• Cadeias de Mensagens: longas navegações a.b().c().d() das quais o chamador não deveria depender. → esconda a caminhada em um método no primeiro objeto.
• Homem do Meio: uma classe ou função que basicamente só 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. Disparar ambos os subagentes em paralelo

Dispa ambas as chamadas de subagentes 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 smells da etapa 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 + regra); e (b) qualquer smell da linha de base que você notar: nomeie-o e cite o trecho. Distinga violações definitivas de julgamentos: quebras de padrões documentados podem ser definitivas, mas smells da linha de base são sempre julgamentos, e um padrão documentado do repositório se sobrepõe à linha de base. Pule o que ferramentas já impõem. Abaixo de 400 palavras."

Prompt do subagente de 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 estão ausentes ou parciais; (b) comportamento no diff que não foi solicitado (aumento de escopo); (c) requisitos que parecem implementados, mas a implementação parece incorreta. Cite a linha da especificação para cada descoberta. 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 as descobertas, pois os dois eixos são deliberadamente separados (veja Por que dois eixos).

Termine com um resumo de uma linha: total de descobertas por eixo, e o pior problema dentro de cada eixo (se houver). Não escolha um único vencedor entre os eixos: isso é a reordenação que a separação existe para 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.

Relatar separadamente impede que um eixo mascare o outro.