ultraeval: avaliar uma habilidade ou base de código → documentação de correção fundamentada e explorável por IA
O markdown é o programa. Um pequeno mecanismo determinístico estrutura a execução, gera o fluxo de trabalho multiagente e impõe uma barreira de fundamentação; você (com subagentes distribuídos) faz a pesquisa, o julgamento e a escrita. Cada descoberta deve resolver para um arquivo:linha real no alvo — a barreira rejeita as alucinadas — e a saída é um backlog priorizado mais cartões TDD por correção que um modelo pode implementar no ciclo red→green→refactor.
Quando usar
- "Avaliar / auditar / classificar / pontuar esta habilidade (ou repositório)"; "está pronta para produção / atende às expectativas?"
- "Revisar esta base de código e me dar um plano de correção / um backlog TDD."
- Proteção contra regressões em suas próprias habilidades após mudanças, ou avaliar uma de terceiros antes de confiar nela.
Não para: uma revisão rápida de código de um arquivo (apenas leia); executar o próprio conjunto de testes do alvo (faça isso diretamente).
O ciclo
init → plan → run(pesquisa → plano-de-teste → executar+barreiras → julgar → resultados) → verificar → backlog(TDD) → pontuar → renderizar
Tudo é uma chamada simples node <diretório-da-habilidade>/scripts/ultraeval.mjs <comando>. Distribuir subagentes é uma otimização que o fluxo de trabalho gerado codifica — nunca um requisito.
Entradas a confirmar
- Alvo — um caminho para a habilidade/repositório a ser avaliado (ou uma URL git que o usuário já clonou localmente).
- Tipo —
skill(habilidade) oucodebase(base de código) (auto-detectado: um SKILL.md ⇒ habilidade). Sobrescreva com--kind. - Categoria — ex. "habilidade de agente", "CLI", "biblioteca", "aplicação web", "ferramenta de segurança". Direciona a rubrica inicial.
- Modo —
audit(auditoria - defeitos, padrão) ·improve(melhoria - oportunidades fundamentadas) ·deep(profundo - ambos). Defina com--mode.
Modos e descoberta de melhorias
O ultraeval encontra duas coisas, ambas fundamentadas e com barreira:
- Defeitos (
audit,deep) — algo está errado; cada um cita umarquivo:linhareal. - Oportunidades (
improve,deep) — uma oportunidade de melhoria fundamentada (saúde interna e produto/capacidade), avaliada como impacto × esforço. Descobertas poranalyze(hotspots determinísticos/dependências/rotatividade/lacunas de teste) →brainstorm(lentes divergentes) →brainstorm --rank(classifica as oportunidades emfindings.jsoncomokind:"opportunity"). A mesma barreira se aplica — uma oportunidade deve ancorar em código/métricas reais, para nunca se tornar um vago "reescrever tudo". Consultereferences/analysis-playbook.md.
Para improve/deep, o plan adiciona as etapas Analyze e Brainstorm ao fluxo de trabalho gerado.
Procedimento
1. Estruturar a execução.
node <diretório-da-habilidade>/scripts/ultraeval.mjs init --target <CAMINHO> --out <EXECUÇÃO> [--kind skill|codebase] [--category "<c>"]
Escreve eval.config.json com as dimensões iniciais (consulte references/rubric-library.md).
2. Gerar o fluxo de trabalho + contratos de subagentes.
node <diretório-da-habilidade>/scripts/ultraeval.mjs plan --run <EXECUÇÃO>
Emite <EXECUÇÃO>/eval.workflow.mjs (um Workflow multiagente pronto para lançar, com os caminhos absolutos do mecanismo e do alvo embutidos), <EXECUÇÃO>/agents/*.md (os contratos de despacho), TEST-PLAN.template.md, dimensions.json, findings.schema.json.
3. Executar a avaliação. Lance o workflow gerado com a ferramenta Workflow do seu harness:
Workflow({ scriptPath: "<EXECUÇÃO>/eval.workflow.mjs" }). Ele sequencia Pesquisa → PlanoDeTeste → Execução → Descobertas → Barreira → Julgamento → Resultados e auto-invoca as barreiras do mecanismo. Se você não tem um harness de workflow, execute as etapas manualmente: leia cada agents/<etapa>.md e despache um subagente conforme o contrato. Consulte references/orchestration.md. Cada subagente recebe o caminho ABSOLUTO para <diretório-da-habilidade>/scripts/ultraeval.mjs — ele tem seu próprio diretório de trabalho atual e não pode resolver um caminho relativo (o plan já embute o caminho absoluto no workflow).
4. Fundamentar cada descoberta. Consolide os resultados em <EXECUÇÃO>/findings.json (esquema: references/gate-contract.md). Cada descoberta cita evidence[].ref como caminho:linha no alvo ou execuçã0:caminhoRelativo#Lnn em um log produzido. Então:
node <diretório-da-habilidade>/scripts/ultraeval.mjs check --run <EXECUÇÃO>
Corrija findings.json até que ele saia com 0 — repare ou exclua descobertas não fundamentadas; nunca enfraqueça a barreira.
5. Verificar (barreira de saída adversarial).
node <diretório-da-habilidade>/scripts/ultraeval.mjs verify --run <EXECUÇÃO> # escreve VERIFY.todo.json
# preencha cada veredito: supported | partial | refuted | unsupported (use subagentes céticos; --shards N --shard i para paralelizar)
node <diretório-da-habilidade>/scripts/ultraeval.mjs verify --run <EXECUÇÃO> --apply <verdicts.json>
node <diretório-da-habilidade>/scripts/ultraeval.mjs check --run <EXECUÇÃO> --semantic --require-verify # barreira de saída — nunca apresente antes que isso passe
Uma descoberta refuted deve ser marcada como dismissed. Uma supported/partial sobrevive.
6. Remediar — a entrega.
node <diretório-da-habilidade>/scripts/ultraeval.mjs backlog --run <EXECUÇÃO> --tdd
Emite BACKLOG.json (uma lista de tarefas legível por máquina, ordenada por prioridade, que um agente downstream pode executar), REMEDIATION.md, e um fixes/FIX-*.md cartão TDD por descoberta confirmada — cada um com uma especificação VERMELHA de teste-falha-primeiro, a mudança VERDE e um comando VERIFY. Consulte references/tdd-remediation.md.
7. Pontuar + renderizar + apresentar.
node <diretório-da-habilidade>/scripts/ultraeval.mjs score --run <EXECUÇÃO> # judges.jsonl + dimensões -> scorecard.json (0-100 + atende-expectativas)
node <diretório-da-habilidade>/scripts/ultraeval.mjs render --run <EXECUÇÃO> # index.html + index.md dashboard (mostra o veredito)
score reduz o painel de juízes judges.jsonl e as dimensões de configuração a um veredito ponderado; uma descoberta P0 ativa (ou qualquer juiz votando não, ou uma pontuação abaixo do limite) define atende-expectativas como falso. Apresente o veredito, o título do backlog P0/P1 e os caminhos (RESULTS.md, BACKLOG.json, fixes/) que um agente de correção deve consumir.
Códigos de saída do CLI: 0 ok / barreira passou · 1 barreira falhou (check/verify) · 2 erro de uso ou execução.
8. (opcional) Conduzir as correções. Passe cada fixes/FIX-*.md para um agente de build implementar TDD — o cartão é escrito para que ele possa ir red→green→refactor sem re-derivar o problema.
O contrato de fundamentação
Uma descoberta só é confiável se sua evidência for resolvível. check abre cada caminho:linha no alvo e confirma que a linha existe e está dentro do intervalo; uma linha obsoleta/inventada é uma falha grave. verify então pergunta a um cético se o conteúdo citado realmente suporta a afirmação. Esta barreira de duas camadas (estrutural + semântica) é o ponto central — gramática completa e regras de aprovação/reprovação em references/gate-contract.md.
Método e rubricas
references/eval-playbook.md— o método pesquisa→plano-de-teste→execução→julgamento→resultados, e como construir uma rubrica pontuada por dimensão.references/orchestration.md— o workflow gerado, os contratos de despacho de subagentes e o invariante do<diretório-da-habilidade>absoluto para a distribuição.references/gate-contract.md— esquema dofindings.json, gramática de referência de evidência, e exatamente o que faz ocheck/verifypassar ou falhar.references/tdd-remediation.md— a forma doBACKLOG.jsone o formato do cartão TDDfixes/FIX-*.md.references/rubric-library.md— dimensões iniciais por categoria de alvo.references/analysis-playbook.md— os sinais doanalyze, as lentes do brainstorm e como as oportunidades permanecem fundamentadas.
Segurança
- ultraeval apenas lê o alvo e escreve sob
<EXECUÇÃO>. Ele nunca executa o código do alvo; o subagente executor pode executar os comandos próprios do alvo (testes, barreiras) — isole repositórios não confiáveis em um sandbox. clean --run <EXECUÇÃO>remove apenas artefatos derivados de barreira/renderização e mantém as entregas;--allremove toda a execução.