ultraeval: evaluar un skill o código fuente → documentación de correcciones fundamentadas y explotables por IA
El markdown es el programa. Un motor determinista minimalista prepara la ejecución, genera el flujo multi-agente y aplica una compuerta de fundamentación; tú (con subagentes en abanico) realizas la investigación, el juicio y la redacción. Cada hallazgo debe resolverse a un archivo:línea real en el objetivo — la compuerta rechaza los alucinados — y la salida es un backlog priorizado más tarjetas TDD por corrección que un modelo puede implementar siguiendo rojo→verde→refactorizar.
Cuándo usarlo
- "Evaluar / auditar / calificar / puntuar este skill (o repositorio)"; "¿está listo para producción / cumple con las expectativas?"
- "Revisar este código fuente y dame un plan de correcciones / un backlog TDD."
- Proteger contra regresiones tus propios skills después de cambios, o evaluar uno de terceros antes de confiar en él.
No para: una revisión rápida de código de un solo archivo (simplemente léelo); ejecutar la propia suite de pruebas del objetivo (hazlo directamente).
El bucle
init → plan → run(investigación → plan-de-pruebas → ejecutar+compuertas → juzgar → resultados) → verificar → backlog(TDD) → puntuar → renderizar
Todo es una llamada simple a node <directorio-del-skill>/scripts/ultraeval.mjs <comando>. Abrir subagentes en abanico es una optimización que codifica el flujo de trabajo generado — nunca un requisito.
Entradas a confirmar
- Objetivo — una ruta al skill/repositorio a evaluar (o una URL git que el usuario ya haya clonado localmente).
- Tipo —
skillocodebase(detección automática: un SKILL.md ⇒ skill). Sobrescribe con--kind. - Categoría — ej. "skill de agente", "CLI", "librería", "aplicación web", "herramienta de seguridad". Dirige la rúbrica inicial.
- Modo —
audit(defectos, por defecto) ·improve(oportunidades de mejora fundamentadas) ·deep(ambos). Establece con--mode.
Modos y descubrimiento de mejoras
ultraeval encuentra dos cosas, ambas fundamentadas y validadas:
- Defectos (
audit,deep) — algo está mal; cada uno cita unarchivo:líneareal. - Oportunidades (
improve,deep) — una vía de mejora fundamentada (salud interna y producto/capacidad), valorada como impacto × esfuerzo. Se descubren medianteanalyze(puntos calientes deterministas/deps/cambios/brechas de pruebas) →brainstorm(perspectivas divergentes) →brainstorm --rank(pliega oportunidades priorizadas enfindings.jsoncomokind:"opportunity"). Se aplica la misma compuerta: una oportunidad debe anclarse a código/métricas reales, para que nunca se convierta en un vago "reescribir todo". Verreferences/analysis-playbook.md.
Para improve/deep, plan añade las etapas Analyze y Brainstorm al flujo de trabajo generado.
Procedimiento
1. Preparar la ejecución.
node <directorio-del-skill>/scripts/ultraeval.mjs init --target <RUTA> --out <EJECUCIÓN> [--kind skill|codebase] [--category "<c>"]
Escribe eval.config.json con dimensiones iniciales (ver references/rubric-library.md).
2. Generar el flujo de trabajo + contratos de subagente.
node <directorio-del-skill>/scripts/ultraeval.mjs plan --run <EJECUCIÓN>
Genera <EJECUCIÓN>/eval.workflow.mjs (un flujo de trabajo multi-agente listo para lanzar, con las rutas absolutas del motor y del objetivo incorporadas), <EJECUCIÓN>/agents/*.md (los contratos de envío), TEST-PLAN.template.md, dimensions.json, findings.schema.json.
3. Ejecutar la evaluación. Lanza el flujo de trabajo generado con la herramienta de Workflow de tu plataforma:
Workflow({ scriptPath: "<EJECUCIÓN>/eval.workflow.mjs" }). Canaliza Investigación → PlanDePruebas → Ejecutar → Hallazgos → Compuerta → Juzgar → Resultados y auto-invoca las compuertas del motor. Si no tienes un entorno de workflow, ejecuta las etapas manualmente: lee cada agents/<etapa>.md y envía un subagente según el contrato. Ver references/orchestration.md. Cada subagente recibe la ruta ABSOLUTA <directorio-del-skill>/scripts/ultraeval.mjs — tiene su propio directorio de trabajo y no puede resolver una ruta relativa (plan ya incorpora la ruta absoluta en el flujo de trabajo).
4. Fundamentar cada hallazgo. Consolida los resultados en <EJECUCIÓN>/findings.json (esquema: references/gate-contract.md). Cada hallazgo cita evidence[].ref como ruta:línea en el objetivo o run:ruta-relativa#Lnn en un registro generado. Luego:
node <directorio-del-skill>/scripts/ultraeval.mjs check --run <EJECUCIÓN>
Arregla findings.json hasta que salga con código 0 — repara o elimina hallazgos sin fundamentar; nunca debilites la compuerta.
5. Verificar (compuerta de salida adversarial).
node <directorio-del-skill>/scripts/ultraeval.mjs verify --run <EJECUCIÓN> # escribe VERIFY.todo.json
# completa cada veredicto: supported | partial | refuted | unsupported (usa subagentes escépticos; --shards N --shard i para paralelizar)
node <directorio-del-skill>/scripts/ultraeval.mjs verify --run <EJECUCIÓN> --apply <veredictos.json>
node <directorio-del-skill>/scripts/ultraeval.mjs check --run <EJECUCIÓN> --semantic --require-verify # compuerta de salida — nunca presentar antes de que esto pase
Un hallazgo refuted debe marcarse como dismissed. Un hallazgo supported/partial sobrevive.
6. Remediar — el entregable.
node <directorio-del-skill>/scripts/ultraeval.mjs backlog --run <EJECUCIÓN> --tdd
Genera BACKLOG.json (una lista de tareas legible por máquina, ordenada por prioridad, que un agente downstream puede ejecutar), REMEDIATION.md, y una tarjeta TDD fixes/FIX-*.md por cada hallazgo confirmado — cada una con una especificación ROJA de prueba fallida primero, el cambio VERDE y un comando VERIFICAR. Ver references/tdd-remediation.md.
7. Puntuar + renderizar + presentar.
node <directorio-del-skill>/scripts/ultraeval.mjs score --run <EJECUCIÓN> # judges.jsonl + dimensiones -> scorecard.json (0-100 + cumple-expectativas)
node <directorio-del-skill>/scripts/ultraeval.mjs render --run <EJECUCIÓN> # index.html + index.md dashboard (muestra el veredicto)
score reduce el judges.jsonl del panel de jueces y las dimensiones de configuración a un veredicto ponderado; un hallazgo P0 activo (o cualquier juez votando no, o una puntuación por debajo del umbral) establece cumple-expectativas en falso. Presenta el veredicto, el titular del backlog P0/P1 y las rutas (RESULTS.md, BACKLOG.json, fixes/) que un agente de correcciones debe consumir.
Códigos de salida en la CLI: 0 ok / compuerta superada · 1 compuerta fallida (check/verify) · 2 error de uso o tiempo de ejecución.
8. (opcional) Ejecutar las correcciones. Entrega cada fixes/FIX-*.md a un agente de construcción para que implemente TDD — la tarjeta está escrita para que pueda pasar de rojo→verde→refactorizar sin tener que re-derivar el problema.
El contrato de fundamentación
Un hallazgo solo es confiable si su evidencia se resuelve. check abre cada ruta:línea en el objetivo y confirma que la línea existe y está dentro del rango; una línea desactualizada o inventada es un fallo grave. verify luego pregunta a un escéptico si el contenido citado realmente respalda la afirmación. Esta compuerta de dos capas (estructural + semántica) es el punto central — gramática completa y reglas de aprobado/fallo en references/gate-contract.md.
Método y rúbricas
references/eval-playbook.md— el método de investigación→plan-de-pruebas→ejecutar→juzgar→resultados, y cómo construir una rúbrica puntuada por dimensión.references/orchestration.md— el flujo de trabajo generado, los contratos de envío de subagentes y el invariante de<directorio-del-skill>absoluto para el abanico.references/gate-contract.md— esquema defindings.json, gramática de referencias de evidencia y exactamente qué hace quecheck/verifyaprueben o fallen.references/tdd-remediation.md— la forma deBACKLOG.jsony el formato de tarjeta TDDfixes/FIX-*.md.references/rubric-library.md— dimensiones iniciales por categoría de objetivo.references/analysis-playbook.md— las señales deanalyze, las perspectivas de brainstorming y cómo las oportunidades se mantienen fundamentadas.
Seguridad
- ultraeval solo lee el objetivo y escribe dentro de
<EJECUCIÓN>. Nunca ejecuta el código del objetivo; el subagente ejecutor puede ejecutar los propios comandos del objetivo (pruebas, compuertas) — aislar repositorios no confiables en un contenedor. clean --run <EJECUCIÓN>elimina solo los artefactos derivados de la compuerta/renderizado y conserva los entregables;--allelimina toda la ejecución.