Polimento de Código

Um protocolo baseado em restrições para normalizar comentários de código e realizar limpeza segura e não semântica. Essa habilidade existe porque o código escrito por humanos tende a carregar comentários casuais, desatualizados ou ausentes, enquanto o objetivo é uma documentação de nível profissional sem alterar o comportamento.

Este arquivo é autossuficiente. Não requer nenhum outro arquivo de habilidade para executar este protocolo.

Primeira Diretriz

Comentários e limpeza não semântica são o trabalho. Lógica nunca é o trabalho. Se uma mudança alterar o que o código faz — não apenas o que ele diz ou como está organizado — ela está fora do escopo, não importa quão obviamente "correto" o conserto pareça.

Quando Usar

Aplique esta habilidade quando:

• O usuário pedir para "limpar", "profissionalizar" ou "polir" código existente
• O código estiver sendo preparado para revisão de código, entrega, código aberto ou documentação
• Um arquivo tiver uma mistura de comentários escritos por humanos e por IA e precisar de uma voz consistente e profissional
• Comentários estiverem desatualizados, ausentes, redundantes ou escritos de forma casual (desabafos, placeholders, piadas internas)
• O usuário quiser que os comentários sejam aprimorados, mas explicitamente não quer que a lógica seja tocada

Não aplique esta habilidade quando:

• O usuário quiser corrigir um bug ou alterar o comportamento (esse é um trabalho diferente — edições de lógica estão fora do escopo aqui)
• O usuário quiser uma reescrita completa ou reestruturação arquitetônica
• O único pedido for adicionar novas funcionalidades ou recursos

Fase 0 — Leitura Completa

Antes de editar qualquer coisa, leia o arquivo inteiro (ou o módulo relevante inteiro se a base de código for grande — não apenas a função em questão). Não comente ou limpe incrementalmente enquanto ainda estiver lendo. Um comentário escrito sem contexto completo é um palpite, e palpites são como comentários "profissionais" acabam errados.

Identifique:

• A linguagem e sua convenção idiomática de comentários/docstrings (JSDoc, docstrings Python, /// para Rust, comentários de documentação XML, etc.)
• Qualquer estilo de comentário de projeto existente já em uso em outro lugar no arquivo — combine-o em vez de importar uma convenção estrangeira
• Qualquer comentário que codifique informações reais e não óbvias (condições de corrida, soluções alternativas para bugs externos, avisos de "não reordene isso", justificativas de regras de negócio)

Fase 1 — Auditoria de Comentários

Classifique cada comentário existente em uma destas categorias antes de tocá-lo:

Fase 2 — Limpeza Não Semântica

O escopo é estritamente limitado a mudanças que não podem alterar o comportamento:

• Indentação e espaços em branco consistentes
• Estilo de chaves/colchetes consistente combinando com o arquivo circundante
• Remoção de código verdadeiramente morto (blocos inalcançáveis) — apenas quando inequívoco e sinalizado no resumo
• Divisão de linhas excessivamente longas para legibilidade
• Renomeação de variáveis locais para clareza é permitida apenas para nomes privados/de escopo local, e apenas quando a melhoria for inequívoca — nunca renomeie nada exportado, público ou referenciado entre arquivos sem chamá-lo explicitamente primeiro

Qualquer coisa além disso — reordenar lógica, extrair funções, mudar fluxo de controle, alterar algoritmos — está fora do escopo desta habilidade.

Fase 3 — Reescrever / Adicionar Comentários

Aplique estes padrões a cada comentário tocado ou adicionado:

…