skill-forge-evolve

Evolução e Melhoria de Skills

Processo

Etapa 1: Diagnosticar o Problema

Pergunte ao usuário ou analise logs para identificar a categoria do problema:

Categoria A: Problemas de Acionamento

• Sub-acionamento: A skill não ativa quando deveria
• Sobre-acionamento: A skill ativa quando não deveria
• Mau acionamento: A sub-skill errada ativa

Categoria B: Problemas de Execução

• Fluxos incompletos: A skill para antes de terminar
• Saída incorreta: Resultados não correspondem às expectativas
• Falta de tratamento de erros: Falhas não são tratadas de forma elegante
• Desempenho: Muito lento ou muitos tokens usados

Categoria C: Problemas de Arquitetura

• Capacidade ausente: Novo caso de uso não coberto
• Problemas de escala: Skill muito grande, precisa de decomposição
• Problemas de referência cruzada: Links para arquivos inexistentes

Categoria D: Problemas de Qualidade

• Resultados inconsistentes: Saídas diferentes para a mesma entrada
• Instruções vagas: Claude interpreta de forma diferente a cada vez
• Falta de exemplos: Nenhuma orientação concreta

Etapa 2: Aplicar Correção por Categoria

Correção: Sub-acionamento

1. Leia a descrição atual
2. Identifique frases de acionamento ausentes
3. Adicione palavras-chave do domínio e paráfrases
4. Adicione menções a tipos de arquivo, se relevante
5. Teste com 5 consultas que agora devem acionar

Causas comuns:

• Descrição muito genérica
• Paráfrases comuns ausentes
• Jargão técnico sem termos leigos

Template de correção:

# Antes (sub-aciona)
description: Analisa qualidade do código

# Depois (acionamento específico)
description: >
  Análise estática de código e avaliação de qualidade. Verifica estilo de código,
  complexidade, vulnerabilidades de segurança e cobertura de testes. Use quando
  o usuário disser "revisão de código", "qualidade do código", "lint", "análise estática",
  "code smell", "auditoria de código" ou "verifique meu código".

Correção: Sobre-acionamento

1. Leia a descrição atual
2. Identifique por que consultas não relacionadas a acionam
3. Adicione acionadores negativos ("NÃO use para...")
4. Torne a descrição mais específica
5. Teste com 5 consultas que NÃO devem acionar

Template de correção:

# Antes (sobre-aciona)
description: Processa documentos para revisão

# Depois (acionamento específico + negativo)
description: >
  Processa documentos PDF legais para extração de cláusulas contratuais e
  revisão de conformidade. Use para contratos legais, NDAs, termos de serviço.
  NÃO use para edição geral de documentos, formatação ou PDFs não legais.

Correção: Problemas de Execução

1. Identifique a etapa com falha no fluxo de trabalho
2. Adicione portões de validação explícitos entre etapas
3. Adicione tratamento de erros com instruções claras de recuperação
4. Adicione caminhos de fallback "Se X falhar, então Y"
5. Considere adicionar um script para operações frágeis

Correção: Problemas de Qualidade

1. Substitua instruções vagas por específicas
2. Adicione exemplos concretos de entrada/saída esperada
3. Adicione comparações explícitas "faça isso, não aquilo"
4. Adicione etapas de verificação de qualidade antes da saída final
5. Considere adicionar um script de validação

Etapa 3: Protocolo de Workspace de Iteração

Use workspaces estruturados para rastrear melhorias entre iterações:

eval-workspace/
  iteration-1/          # Primeira versão
    eval-0/with_skill/  # Resultados da avaliação
    eval-0/baseline/
    benchmark.json      # Métricas agregadas
    benchmark.md        # Relatório legível
    feedback.json       # Feedback do usuário
  iteration-2/          # Após primeira melhoria
    eval-0/with_skill/
    eval-0/baseline/
    benchmark.json
    benchmark.md
    feedback.json

O loop de iteração:

1. Aplique a correção na skill
2. Execute /skill-forge eval <caminho> em iteration-<N+1>/
3. Execute /skill-forge benchmark <caminho> com --previous iteration-<N>/
4. Revise a comparação de benchmark para regressões
5. Colete feedback do usuário em feedback.json
6. Leia o feedback e itere (volte à Etapa 2)

Pare de iterar quando:

• O usuário disser que está satisfeito
• Todo feedback estiver vazio (tudo parece bom)
• O benchmark não mostrar progresso significativo entre iterações
• A taxa de aprovação atingir os limites definidos

Etapa 3b: Loop de Auto-Annealing

Para correções rápidas sem a pipeline completa de avaliação:

1. Aplique a correção
2. Teste com o caso de falha original
3. Teste com 3 outros casos (verificação de regressão)
4. Se a correção funcionar:
   -> Atualize a diretiva/SKILL.md
   -> Documente o aprendizado em referências ou SKILL.md
5. Se a correção falhar:
   -> Diagnostique por que
   -> Tente uma abordagem alternativa
   -> Repita

Etapa 3c: Loop de Otimização de Descrição

Para problemas de acionamento (Categoria A), use o loop de otimização automatizado:

1. Gere conjunto de avaliação de acionamento: python scripts/generate_eval_set.py <caminho>
2. Revise e refine o conjunto de avaliação com o usuário
3. Execute otimização: python scripts/optimize_description.py <caminho> --eval-set evals.json
4. Revise as pontuações de divisão treino/teste e sugestões de melhoria
5. Aplique as alterações de descrição sugeridas
6. Reexecute a otimização para medir melhoria
7. Selecione a descrição com a maior pontuação de teste (não treino — evita overfitting)
8. Itere até 5 vezes ou até a pontuação de teste estagnar

Etapa 4: Evolução da Arquitetura

Quando uma skill supera seu tier:

Tier 1 -> Tier 2 (precisa de scripts):

1. Identifique a operação frágil/determinística
2. Crie script em scripts/
3. Atualize SKILL.md para referenciar o script
4. Teste o script de forma independente

Tier 2 -> Tier 3 (precisa de sub-skills):

1. Identifique fluxos de trabalho distintos que podem ser separados
2. Extraia cada um em seu próprio skills/{pai}-{filho}/SKILL.md
3. Atualize o SKILL.md principal com tabela de roteamento
4. Mova conhecimento compartilhado para references/
5. Atualize install.sh

Tier 3 -> Tier 4 (precisa de agentes):

1. Identifique fluxos de trabalho que podem ser executados em paralelo
2. Crie definições de agente em agents/
3. Atualize a sub-skill de auditoria/análise completa para delegar a agentes
4. Teste execução paralela

Etapa 5: Gerenciamento de Versão

Após a evolução:

1. Atualize metadata.version no frontmatter (se presente)
2. Adicione aprendizado ao SKILL.md ou arquivo de referência
3. Atualize quaisquer referências cruzadas afetadas
4. Reexecute validação: python scripts/validate_skill.py <caminho>
5. Teste fluxo de trabalho completo de ponta a ponta

Padrões Comuns de Evolução

Padrão: Adicionar Detecção de Indústria

Quando uma skill precisa adaptar comportamento por tipo de usuário:

## Detecção de Indústria
Detecte o tipo de usuário a partir do contexto:
- **Tipo A**: [sinais] -> [comportamento]
- **Tipo B**: [sinais] -> [comportamento]

Padrão: Adicionar Gates de Qualidade

Quando a qualidade da saída é inconsistente:

## Gates de Qualidade
Antes de entregar a saída:
- [ ] [Verificação 1]
- [ ] [Verificação 2]
- [ ] [Verificação 3]

Padrão: Adicionar Scoring

Quando os usuários precisam de saída mensurável:

## Scoring (0-100)
| Categoria | Peso |
|-----------|------|
| Categoria A | 30% |
| Categoria B | 30% |
| Categoria C | 20% |
| Categoria D | 20% |