tacticaldoll/nlp-agent-skills

Assay

Use esta habilidade para realizar uma revisão de código estática local baseada em portões. A revisão abre portões de qualidade em ordem; uma falha em um portão inferior bloqueia portões superiores, pois julgamentos posteriores não são úteis quando a higiene básica, nomenclatura ou tratamento de erros já estão quebrados.

Esta habilidade não chama serviços remotos, publica comentários, aprova código ou modifica arquivos. Ela revisa entradas locais ou coladas e produz um relatório estruturado.

Fluxo de Trabalho

Fase 0: Resolver Entrada Local

Normalize a entrada do usuário em um escopo de revisão:

Entrada	Resolução
Código ou diff colado	Revisar o conteúdo fornecido diretamente
Caminhos de arquivos locais	Ler o conteúdo completo do arquivo; sem contexto de diff, a menos que disponível
Diff git local	Revisar arquivos alterados e hunks
Hash de commit ou intervalo	Usar diff git local quando disponível
Nome de branch	Usar diff git da base de merge quando disponível
Solicitação ambígua	Perguntar por arquivos, diff, commit/intervalo, branch ou código colado

Não busque dados de MR/PR, chame APIs remotas ou exija autenticação. Se o contexto remoto for necessário, peça ao usuário para fornecer um diff local ou conteúdo colado.

Fase 1: Calibrar Profundidade da Revisão

Escolha quantos portões abrir. O padrão é Portões 1-5 para alterações locais comuns.

Contexto	Faixa de Portões
Rascunho, WIP, código exploratório	Portões 1-3
Funcionalidade comum ou ferramenta interna	Portões 1-5
Biblioteca compartilhada, caminho de produção ou API pública	Portões 1-7
Código sensível à segurança, autenticação, criptografia, execução de comandos ou limite de entrada do usuário	Portões 1-8

Quando ambíguo, pergunte qual destino ou nível de risco o código possui.

Fase 2: Triagem de Escopos Grandes

Quando o escopo da revisão contiver mais de 5 arquivos, execute uma triagem rápida antes da inspeção profunda. Para 5 arquivos ou menos, pule a triagem e prossiga para a extração estrutural.

Verificações de triagem:

#	Verificação	Sinal de Falha
1	Código morto	Código comentado, imports não utilizados, saída de depuração
2	Clareza de nomenclatura	Nomes públicos são vagos ou enganosos
3	Profundidade de aninhamento	Aninhamento mais profundo que 3 níveis
4	Tamanho da função	Funções longas o suficiente para esconder múltiplas responsabilidades
5	Engolir erros	Catch/except vazio ou falha ignorada
6	Mistura de domínios	I/O e lógica de negócios misturados em uma unidade
7	Montagem bruta de campos	Condições complexas sem auxiliares semânticos
8	Cheiro de duplicação	Lógica similar aparece repetidamente
9	Cheiro de segurança	Segredos, interpolação insegura, logs sensíveis, entrada perigosa não verificada

Classifique arquivos:

Classe	Critério	Próxima Ação
Vermelho	3 ou mais verificações falham	Inspeção completa do portão
Amarelo	1-2 verificações falham	Inspecionar portão alvo e todos os portões inferiores
Verde	0 verificações falham	Passar, a menos que especificamente solicitado

Cheiro de segurança é de dupla via: reporte-o como um alerta de triagem mesmo que o Portão 8 esteja bloqueado por um portão inferior.

Fase 3: Extração Estrutural

Antes de abrir portões, extraia a estrutura de cada função, classe, módulo ou unidade de código relevante revisada. Use a extração para guiar a revisão do portão; não confie apenas no texto bruto do diff.

Registre:

• Closures, callbacks ou funções aninhadas.
• Objetos inline ou entidades locais com comportamento.
• Operações de I/O e efeitos colaterais externos.
• Aninhamento mais profundo e o motivo para ele.
• Distribuição de domínio: infraestrutura, negócios, apresentação ou misto.
• Ciclo de vida: único, persistente ou misto.
• Variáveis capturadas e dependências ocultas.
• Anomalias óbvias descobertas durante a extração.
• Fonte de verdade disponível para o Portão 6: localize qualquer documento de especificação ou governança (openspec/, PROJECT.md, AGENTS.md, ADRs, um issue vinculado) para julgar a lógica, ou anote que nenhum foi encontrado.

Fase 4: Revisão Sequencial de Portões

Leia references/gates.md para definições dos portões.

Abra portões em ordem. Se um portão falhar, pare de abrir portões superiores para aquele arquivo ou escopo de revisão. Não fabrique descobertas. Silêncio significa conformidade para seções de detalhes; o índice do portão ainda registra quais portões abriram, passaram, falharam ou foram bloqueados.

Fase 5: Relatório

Produza um relatório usando este formato:

## Registro de Revisão

**Fonte**: [referência de entrada]
**Calibração**: Portões 1-[N] ([motivo])
**Triagem**: [pulada | Vermelho M / Amarelo N / Verde K]
**Veredito**: [APROVADO | FALHA no Portão N]

### Índice de Portões

| Portão | Foco | Status |
|---:|---|---|
| 1 | Higiene de Formatação e Sintaxe | [aprovado | falha | bloqueado | não inspecionado] |
| 2 | Nomenclatura e Legibilidade | [aprovado | falha | bloqueado | não inspecionado] |
| 3 | Tratamento de Erros e Observabilidade | [aprovado | falha | bloqueado | não inspecionado] |
| 4 | Fluxo de Controle e Clareza Estrutural | [aprovado | falha | bloqueado | não inspecionado] |
| 5 | Responsabilidade e Limites | [aprovado | falha | bloqueado | não inspecionado] |
| 6 | Integridade da Lógica de Negócios | [aprovado | falha | bloqueado | não inspecionado] |
| 7 | Desduplicação e Composição | [aprovado | falha | bloqueado | não inspecionado] |
| 8 | Segurança e Integridade de Parâmetros | [aprovado | falha | bloqueado | não inspecionado] |

### Alerta de Triagem de Segurança

[Incluir apenas quando a verificação 9 da triagem falhar.]

### Portão N: [nome]

| # | Localização | Violação | Correção |
|---|---|---|---|
| 1 | `arquivo:linha` | Portão N: padrão específico violado | Correção concreta |

### Apêndice Estrutural

[Incluir resumos para unidades de código relacionadas às descobertas.]

Fase 6: Plano de Correção Opcional

Produza um plano de correção apenas quando o usuário solicitar um.

Regras do plano de correção:

• Uma violação por correção.
• A ordem de correção segue a ordem dos portões.
• Dentro do mesmo portão, ordenar por arquivo e linha, a menos que dependências lógicas exijam o contrário.
• Sem correções oportunistas.
• Cada correção inclui critérios de verificação.

Regras

• Revisar apenas; não modifique o código.
• Use apenas entradas locais ou coladas; não chame APIs remotas de PR/MR.
• Abra portões sequencialmente e pare no primeiro portão com falha.
• Reporte alertas de triagem de segurança mesmo quando a inspeção profunda de segurança estiver bloqueada.
• Dê correções concretas; evite sugestões vagas como "considere melhorar".
• Se todos os portões abertos passarem, o Índice de Portões é o relatório; não invente descobertas.
• Mencione quando testes, builds ou verificações de tempo de execução não foram executados.
• Permaneça na sua área; faça a transferência no limite. Esta habilidade é revisão estática e local apenas. Para correção de tempo de execução/comportamental, aponte para verificar; para análise de segurança profunda além das verificações superficiais do Portão 8, aponte para revisão-de-segurança. Nomeie a transferência em vez de fazer metade do trabalho da outra habilidade.