multi-evaluator

Bucle de mejora de diseño multi-evaluador

Rondas de revisión independiente hasta que el producto esté listo para personas: cada recorrido obtiene 9 o mejor de cada revisor, no hay correcciones de alta gravedad abiertas, los revisores coinciden en un punto, y eso se ha mantenido durante dos rondas consecutivas. Un 10 unánime es una señal para verificar el brief, no el objetivo. Las puntuaciones de IA son una señal fuerte, no una prueba: cuando el bucle dice listo, lo prueban personas reales por primera vez, y donde discrepan de la IA, las personas ganan.

Todo se ejecuta a través de una herramienta de línea de comandos, scripts/eval_loop.py (junto a este archivo), por lo que una persona, este agente o cualquier otro agente obtiene los mismos resultados. Cada comando toma --dir <carpeta de revisión>, y status --json siempre indica dónde está el bucle y qué hacer a continuación. Necesita Python 3.9 o posterior, Node.js 18 o posterior y Google Chrome o Chromium. Nada más que instalar.

A continuación, LOOP significa python3 <carpeta de esta skill>/scripts/eval_loop.py.

Antes de empezar (cada skill de mStack)

• Si ~/.mstack/config.json lista multi-evaluator bajo "disabled", o la persona dijo que no lo use para esta tarea, trabaje de la forma habitual.
• Si ~/.mstack/learned/multi-evaluator.md existe, léalo: contiene las mejoras aceptadas de esta persona, y tienen prioridad sobre este archivo.
• Cuando el bucle termine (o se detenga), registre privadamente cómo fue: python3 <carpeta de skill de mstack>/scripts/mstack.py log multi-evaluator --outcome reached|partial|not-reached --needed-user "..." --stalled "..." (la skill de mstack está junto a esta).

1. Recorridos y criterios primero

Antes de cualquier revisión, acuerde con la persona lo que una persona real debe poder hacer, de principio a fin.

1. LOOP init --dir design-review --name "<producto>" --start "<comando que lo inicia, con {port}>" --cwd <su carpeta> (o --url <dirección> para algo ya en ejecución, como un sitio de pruebas).
2. Complete design-review/mstack-eval.json con la persona. Consulte references/config.md para cada campo:
   • about y persona: qué es el producto y quién lo juzga. Mantenga la dirección de diseño y las restricciones fuera de about y dentro de rules: se muestran a los revisores como "no puntuado", por lo que el brief nunca entrega la respuesta que espera escuchar.
   • journeys: de 3 a 6 tareas reales, cada una de principio a fin ("Agregar un libro y verlo en la lista").
   • views: las pantallas fijas capturadas en cada ronda (escritorio, teléfono, tema oscuro). Tema claro primero.
   • criteria: el piso es claro, rápido, confiable, familiar, calmado, funciona en todas partes. stages agregan más criterios a medida que el producto madura (tiempo de valor, recuperación de errores, texto, experiencia del agente, accesibilidad medida, velocidad, prueba de cinco segundos, tono emocional, consistencia, seguridad de datos, deleite). Active una etapa con "active": true o "from_round": <n> cuando las puntuaciones muestren que se cumple el piso.
   • reviewers: al menos dos, de diferentes fabricantes de IA. El valor predeterminado es Claude (ejecutado por usted, el agente) y Codex (ejecutado por la herramienta con codex exec).
   • control: la verificación de ruido (recomendada). La primera captura congela las pantallas de esa ronda en control/; cada revisor las puntúa cada ronda como recorrido control, y el informe muestra cuánto se movió esa puntuación. Un cambio menor que ese movimiento es ruido, no progreso.
3. Muestre a la persona los recorridos y criterios y obtenga un sí antes de la ronda 1.

2. Cada ronda

LOOP start-round --dir design-review          # abre rounds/r<N>/, captura los criterios de esta ronda
                                              # escriba rounds/r<N>/changes.md: qué cambió, una viñeta cada uno
LOOP capture --dir design-review              # las mismas pantallas, capturadas de la misma manera, cada ronda
LOOP brief --dir design-review                # briefs de puntuación ciega en rounds/r<N>/briefs/, más briefs -compare desde la ronda 2
LOOP review --dir design-review               # ejecuta revisores de línea de comandos (Codex) en paralelo; ejecútelo en segundo plano

Al mismo tiempo, ejecute usted mismo cada revisor cuyo kind sea agent, en contexto fresco:

• Claude Code: inicie un subagente (la herramienta Agent, propósito general) cuya indicación sea el texto completo de rounds/r<N>/briefs/claude.md. No agregue sus propias opiniones, la respuesta esperada ni puntuaciones anteriores.
• Cualquier otro agente: abra una nueva sesión o hilo con el brief como la única instrucción.
• Un revisor de kind: "chat" (opcional, opt-in: Grok, ChatGPT o Gemini en el navegador con sesión iniciada de la propia persona, sin clave API): solo con el sí de la persona sobre lo que se puede compartir, abra un nuevo chat privado, pegue rounds/r<N>/briefs/<id>.md, suba las pantallas fijas de esta ronda si el producto no es público, guarde la respuesta, cierre la pestaña, luego verdict. Ve capturas de pantalla, no el producto en vivo, por lo que es un desempate: nunca cuenta para "listo para personas" y nunca puede ser el único revisor.

Cuando responda, guarde su JSON (la herramienta lo verifica y rechaza una respuesta que no se ajuste al formato):

LOOP verdict --dir design-review --reviewer claude reply.json      # o canalice la respuesta con -

Ciego primero, comparación después. El brief de puntuación muestra solo esta ronda: sin capturas de pantalla anteriores, sin puntuaciones anteriores, sin dirección de diseño, por lo que la puntuación significa lo mismo en la ronda 1 y en la ronda 9. Desde la ronda 2 también hay rounds/r<N>/briefs/<reviewer>-compare.md. Entréguelo al mismo revisor después de que su veredicto esté guardado (la misma sesión está bien; ya no es ciego) y guarde la respuesta aparte de la puntuación:

LOOP verdict --dir design-review --reviewer claude --compare compare-reply.json
LOOP report --dir design-review                                     # escribe design-review/report.html

La comparación nunca cambia una puntuación; el informe la muestra bajo "Qué cambió".

Luego muestre a la persona el informe y las capturas de pantalla de tema claro (rounds/r<N>/shots/). Envíe una notificación si su agente puede (en Claude Code, PushNotification) cuando el informe de una ronda esté listo o el bucle necesite una decisión; el comando notify de la configuración también puede enviar una (consulte references/config.md).

3. Arreglar, luego repetir

1. Comience desde la lista Hacer estos a continuación del informe (primero correcciones en un recorrido que todos los revisores marcaron, luego alta gravedad, luego la brecha más grande de "si se arregla"). Cuando la tabla de recorridos diga que los revisores discrepan en 2 o más, revise ese recorrido usted mismo antes de actuar sobre cualquiera de las puntuaciones.
2. Haga las correcciones en el producto, ejecute sus propias pruebas y escriba el changes.md de la siguiente ronda.
3. LOOP start-round, y repita hasta que LOOP status diga listo para personas (la regla de parada anterior, mantenida durante dos rondas). Si una ronda pasa, no cambie nada grande y ejecute una más para que se mantenga. Después de max_rounds (predeterminado 6) sin alcanzarlo, status dice que se detenga y hable con la persona: los recorridos o criterios pueden estar pidiendo algo que el producto no debería hacer.
4. Luego, personas reales: cinco usuarios primerizos prueban los recorridos sin ayuda. Registre su tiempo, tropiezos y palabras en rounds/r<N>/people.md (una viñeta cada uno; el informe los muestra). Donde discrepen de los revisores de IA, las personas ganan: convierta lo que encontraron en recorridos o criterios para la siguiente ronda.

Reglas

• Los revisores nunca ven los veredictos de los demás, rondas anteriores, puntuaciones anteriores o el informe mientras puntúan; el brief se los dice. La comparación con la ronda anterior es una pasada separada, después del veredicto.
• Las mismas vistas, capturadas de la misma manera, cada ronda, para que el antes y el después se comparen de manera similar.
• Nunca permita que un revisor envíe pagos reales, mensajes o datos personales. Use datos de demostración y una copia nueva.
• Los revisores en sandbox (Codex) no pueden iniciar Chrome: review inicia un Chrome compartido sin cabeza y el brief les dice que pongan MSTACK_CDP_PORT=<puerto> delante del comando del controlador.
• Si la respuesta de un revisor no se ajusta, lea rounds/r<N>/work/<reviewer>/raw-reply.txt, luego vuelva a ejecutarlo. La herramienta rechaza un 10 que aún propone correcciones, y un "si se arregla" por debajo de la puntuación.
• Mantenga la carpeta de revisión en el repositorio del producto (o junto a él) para que cada ronda se conserve.

Archivos

• scripts/eval_loop.py: la herramienta de línea de comandos (init, status, start-round, capture, brief, serve, review, verdict, validate, report, notify).
• scripts/drive.mjs: el controlador de recorrido, un Chrome real sin cabeza; los revisores lo usan directamente.
• scripts/report.py: el constructor de informes. scripts/readiness.py: la regla de parada y la verificación de ruido.
• templates/mstack-eval.json: la configuración de inicio.
• references/config.md: cada campo de configuración. references/verdict-format.md: el formato de respuesta. references/method.md: por qué el bucle funciona de esta manera y cómo crecen los criterios.