Brians-brain/claude-skills

Comunique-se com o usuário e produza relatórios em português (Brasil).

Analise o diff entre HEAD e o ponto fixo fornecido pelo usuário em dois eixos:

• Normas (Standards): O código segue as normas documentadas de escrita deste repositório?
• Especificação (Spec): O código implementa fielmente a issue ou especificação original?

Ambos os eixos são executados por subagentes paralelos para evitar contaminação de contexto, e esta skill consolida as descobertas.

O issue tracker já deve ter sido fornecido a você. Caso contrário, informe ao usuário para executar primeiro /setup-matt-pocock-skills.

Fluxo

1. Determinar o ponto fixo

O ponto fixo é o que o usuário disser (SHA de commit, nome de branch, tag, main, HEAD~5, etc.). Se ele não especificar, pergunte.

Anote o comando diff de uma vez: git diff <fixed-point>...HEAD (três pontos, compara com o merge-base). Anote também a lista de commits com git log <fixed-point>..HEAD --oneline.

Antes de prosseguir, confirme que o ponto fixo pode ser resolvido (git rev-parse <fixed-point>) e que o diff não está vazio. Referências inválidas ou diffs vazios devem falhar aqui, não nos subagentes paralelos.

2. Encontrar a fonte da especificação

Procure a especificação original na seguinte ordem:

1. Referências a issues nas mensagens de commit (#123, Closes #45, !67 do GitLab, etc.), obtidas por meio do fluxo no arquivo do tracker.
2. Caminho passado pelo usuário como parâmetro.
3. Arquivos de especificação em docs/, specs/ ou .scratch/ que correspondam 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á especificação, o subagente Spec é pulado e reporta "Nenhuma especificação disponível".

3. Encontrar a fonte das normas

Pesquise no repositório todos os arquivos que documentam como o código deve ser escrito. Se CODING_STANDARDS.md ou CONTRIBUTING.md existirem, inclua-os obrigatoriamente. Em projetos Python, verifique também as configurações de linters/formatters (ruff, black, mypy, etc.) em pyproject.toml, mas não revise regras que já são aplicadas pela ferramenta.

Além do que está documentado no repositório, o eixo Normas sempre carrega a base de code smells abaixo: um conjunto fixo de code smells do Fowler (Capítulo 3 de "Refatoração"), aplicável mesmo que o repositório não tenha documentado nada. Duas regras o regem:

• Repositório tem prioridade. Normas documentadas no repositório sempre vencem; quando uma norma aprova algo que a base marcaria, não marque esse code smell.
• É sempre um julgamento. Cada code smell é uma heurística rotulada ("pode haver Feature Envy"), nunca uma violação rígida. E, como qualquer norma aqui, ignore o que já é aplicado por ferramentas.

Cada code smell é descrito como "O que é → Como corrigir"; aplique-o ao diff:

• Nome Misterioso (Mysterious Name): O nome de uma função, variável ou tipo não revela o que faz ou contém. → Renomeie; se não conseguir pensar em um nome honesto, o design em si é nebuloso.
• Código Duplicado (Duplicated Code): A mesma forma lógica aparece em mais de um bloco ou arquivo nesta alteração. → Extraia a forma comum e chame-a de ambos os lados.
• Inveja de Recursos (Feature Envy): Um método acessa mais dados de outro objeto do que dos seus próprios. → Mova o método para o objeto dos dados que ele inveja.
• Grumos de Dados (Data Clumps): Os mesmos campos ou parâmetros sempre aparecem juntos (um tipo querendo nascer). → Agrupe-os em um tipo e passe esse tipo.
• Obsessão por Primitivos (Primitive Obsession): Usar um tipo primitivo ou string para representar um conceito de domínio que merece seu próprio tipo (ex.: str para número de peça, float para valor monetário com moeda). → Dê a esse conceito um pequeno tipo próprio (ex.: dataclass).
• Switch Repetido (Repeated Switches): A mesma sequência de match/if sobre o mesmo tipo aparece repetidamente nesta alteração. → Use polimorfismo ou uma tabela de consulta compartilhada.
• Cirurgia com Espingarda (Shotgun Surgery): Uma mudança lógica força alterações espalhadas em muitos arquivos no diff. → Centralize o que muda junto em um módulo.
• Mudança Divergente (Divergent Change): Um arquivo ou módulo é modificado por motivos não relacionados. → Separe, fazendo com que cada módulo mude por apenas um motivo.
• Generalidade Especulativa (Speculative Generality): Abstrações, parâmetros ou hooks adicionados para requisitos que não estão na especificação. → Remova; inline de volta, espere a necessidade real surgir.
• Cadeias de Mensagens (Message Chains): Longas navegações a.b().c().d() que o chamador não deveria conhecer. → Esconda a travessia atrás de um método no primeiro objeto.
• Homem do Meio (Middle Man): Uma classe ou função que principalmente delega para outra. → Remova-a e chame o destino real diretamente.
• Legado Recusado (Refused Bequest): Uma subclasse ou implementador ignora ou sobrescreve a maior parte do que herda. → Troque herança por composição.

4. Disparar dois subagentes paralelos

Dispa duas chamadas de subagente simultaneamente (em primeiro plano) e consolide os relatórios retornados.

Prompt do subagente Normas deve conter:

• O comando diff completo e a lista de commits.
• A lista de arquivos de normas encontrados no passo 3, mais a base de code smells do passo 3 colada na íntegra (o subagente não tem outra forma de obtê-la).
• Instrução: "Relate em português (Brasil), marcando arquivo/bloco quando relevante: (a) cada violação das normas documentadas pelo diff: cite a norma (arquivo + regra); e (b) qualquer code smell da base que você encontrar: nomeie-o e cite o bloco. Diferencie violações rígidas de julgamentos: violações de normas documentadas podem ser rígidas, mas code smells da base são sempre julgamentos, e normas documentadas do repositório têm prioridade sobre a base. Ignore o que já é aplicado por ferramentas. Máximo de 400 palavras."

Prompt do subagente Spec deve conter:

• O comando diff e a lista de commits.
• O caminho da especificação ou seu conteúdo obtido.
• Instrução: "Relate em português (Brasil): (a) requisitos que a especificação exige, mas estão ausentes ou implementados apenas parcialmente; (b) comportamentos no diff que não foram solicitados (escopo inchado); (c) requisitos que parecem implementados, mas de forma incorreta. Para cada descoberta, cite o texto correspondente da especificação. Máximo de 400 palavras."

Se não houver especificação, pule o subagente Spec e anote no relatório final.

5. Consolidar

Coloque os dois relatórios sob os cabeçalhos ## Normas e ## Especificação, transcrevendo-os na íntegra ou com pequenos ajustes. Não mescle nem reordene as descobertas, pois os dois eixos são intencionalmente separados (veja "Por que dois eixos").

Finalize com uma linha de resumo: total de descobertas por eixo e o problema mais grave dentro de cada eixo (se houver). Não selecione um vencedor entre eixos: é exatamente isso que a separação em dois eixos visa evitar.

Por que dois eixos

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

• Segue todas as normas, mas implementa a coisa errada → Normas aprovado, Especificação reprovado.
• Faz exatamente o que a issue pede, mas quebra as convenções do projeto → Especificação aprovado, Normas reprovado.

Relatar separadamente impede que um eixo mascare o outro.