skill-forge-benchmark

Benchmarking de Habilidade e Acompanhamento de Desempenho

Meça e compare o desempenho da habilidade entre iterações com rigor estatístico usando múltiplas tentativas, análise de variância e acompanhamento de tendências.

Processo

Etapa 1: Definir Configuração de Benchmark

Aceitar configuração como:

• Conjunto de avaliação existente: Caminho para evals/evals.json (de /skill-forge eval)
• Configuração de benchmark: Configuração personalizada com contagem de tentativas e limites

Esquema de configuração de benchmark:

{
  "skill_name": "minha-habilidade",
  "skill_path": "./minha-habilidade",
  "eval_set_path": "./evals/evals.json",
  "trials_per_eval": 3,
  "baseline_type": "no_skill",
  "previous_benchmark": null,
  "thresholds": {
    "min_pass_rate": 0.8,
    "max_avg_tokens": 100000,
    "max_avg_duration_seconds": 120,
    "min_improvement_ratio": 1.0
  }
}

Etapa 2: Executar Execuções de Benchmark

Para cada avaliação, execute trials_per_eval vezes (padrão: 3) para obter métricas confiáveis:

1. Executar execuções com habilidade (3x por avaliação)
2. Executar execuções de linha de base (3x por avaliação)
3. Capturar por execução: aprovação/reprovação, contagem de tokens, duração
4. Salvar timing.json e grading.json de cada execução

Use agents/skill-forge-executor.md para execução paralela quando possível.

Etapa 3: Agregar Resultados

Execute python scripts/aggregate_benchmark.py <workspace>/iteration-<N> --skill-name <name>:

Esquema de saída benchmark.json:

{
  "skill_name": "minha-habilidade",
  "iteration": 1,
  "timestamp": "2026-03-06T12:00:00Z",
  "summary": {
    "total_evals": 10,
    "with_skill": {
      "pass_rate": 0.87,
      "pass_rate_std": 0.05,
      "avg_tokens": 45000,
      "avg_duration_seconds": 34.2
    },
    "baseline": {
      "pass_rate": 0.60,
      "pass_rate_std": 0.08,
      "avg_tokens": 62000,
      "avg_duration_seconds": 52.1
    },
    "improvement_ratio": 1.45,
    "token_savings_ratio": 0.73,
    "time_savings_ratio": 0.66
  },
  "per_eval": [
    {
      "eval_id": 0,
      "eval_name": "basic-trigger",
      "with_skill": {"pass_rate": 1.0, "avg_tokens": 30000, "avg_duration_seconds": 20.1},
      "baseline": {"pass_rate": 0.67, "avg_tokens": 50000, "avg_duration_seconds": 45.0},
      "trials": 3
    }
  ],
  "thresholds_met": {
    "min_pass_rate": true,
    "max_avg_tokens": true,
    "max_avg_duration_seconds": true,
    "min_improvement_ratio": true
  }
}

Etapa 4: Comparar com Iterações Anteriores

Se previous_benchmark for fornecido ou existir iteration-<N-1> anterior:

1. Carregar benchmark.json anterior
2. Calcular delta por métrica:
   • Mudança na taxa de aprovação
   • Mudança no uso de tokens
   • Mudança na duração
   • Novas regressões (avaliações que passavam antes, mas falham agora)
   • Novas melhorias (avaliações que falhavam antes, mas passam agora)

Etapa 5: Gerar Relatório de Benchmark

# Relatório de Benchmark: [skill-name]

## Iteração [N] vs [N-1]

### Resumo
| Métrica | Atual | Anterior | Delta | Limite | Status |
|---------|-------|----------|-------|--------|--------|
| Taxa de Aprovação | 87% | 78% | +9% | >= 80% | APROVADO |
| Média de Tokens | 45K | 52K | -13% | <= 100K | APROVADO |
| Tempo Médio | 34s | 41s | -17% | <= 120s | APROVADO |
| Melhoria | 1.45x | 1.30x | +0.15x | >= 1.0x | APROVADO |

### Regressões (Ação Necessária)
| Avaliação | Anterior | Atual | Observações |
|-----------|----------|-------|-------------|
| eval-5 | APROVADO | REPROVADO | Saída sem seção obrigatória |

### Melhorias
| Avaliação | Anterior | Atual | Observações |
|-----------|----------|-------|-------------|
| eval-3 | REPROVADO | APROVADO | Tratamento de erros agora funciona |

### Detalhamento por Avaliação
[Tabela completa de detalhamento]

### Análise de Variância
| Avaliação | Taxa de Aprovação | Desvio Padrão | Tentativas | Confiabilidade |
|-----------|-------------------|---------------|------------|----------------|
| eval-0 | 100% | 0.00 | 3 | Alta |
| eval-1 | 67% | 0.47 | 3 | Baixa (investigar) |

### Recomendações
[Com base em regressões, avaliações de baixa confiabilidade e falhas de limite]

Etapa 6: Bloqueio por Limite

Se algum limite falhar:

1. Sinalizar como REPROVADO com detalhes específicos do limite
2. Listar quais avaliações causaram a falha
3. Recomendar executar /skill-forge evolve para resolver os problemas
4. NÃO aprovar para publicação até que os limites sejam aprovados

Tratamento de Erros

• Tentativas instáveis: Se uma tentativa expirar ou falhar, excluí-la do cálculo de variância e anotar "trials_completed" vs "trials_requested" nos resultados por avaliação
• Tentativas insuficientes: Se menos de 2 tentativas forem concluídas para uma avaliação, sinalizar a variância como "unreliable" no relatório
• Linha de base ausente: Se as execuções de linha de base falharem completamente, relatar apenas resultados com habilidade e pular o improvement_ratio
• Casos limite de limite: Se a taxa de aprovação for exatamente igual ao limite, tratar como APROVADO

Integração com Outras Sub-habilidades

• skill-forge-eval: Fornece o conjunto de avaliação e a infraestrutura de classificação
• skill-forge-evolve: Recebe falhas de benchmark como alvos de melhoria
• skill-forge-publish: Requer aprovação no benchmark (pontuação >= limites) antes de publicar
• skill-forge-review: Pode incluir resumo do benchmark no relatório de revisão