prototype y research: responder preguntas de diseño antes de construir con tu agente

No todas las preguntas de un diseño se resuelven hablando. "¿Este modelo de estados aguanta el caso raro?" o "¿cómo debería verse este panel?" piden algo que puedas tocar. Y "¿qué límites tiene la API de este proveedor?" pide leer documentación, no opinar. prototype y research son la pareja para esas dos situaciones: una fabrica código desechable que responde una pregunta, y la otra manda a un agente en segundo plano a investigar en fuentes primarias mientras tú sigues trabajando.

Es la novena parte de la guía de las skills de Matt Pocock (repositorio mattpocock/skills, licencia MIT). Las dos son skills que el modelo puede invocar solo cuando la tarea encaja.

Dónde encajan en el flujo

Durante un grill-with-docs aparecen preguntas que la conversación no puede cerrar. ask-matt propone un desvío:

• Pregunta de hechos (documentación, APIs de terceros, código fuente): research en segundo plano. El resultado vuelve al interrogatorio.
• Pregunta que necesita una respuesta ejecutable (estado, lógica de negocio, una interfaz que hay que ver): /handoff hacia una sesión nueva, prototype allí, y /handoff de vuelta con lo aprendido.

En wayfinder, que vemos en la parte 10, son dos de los cuatro tipos de ticket: research (sin humano) y prototype (con humano).

prototype: código desechable que responde una pregunta

La definición de la skill: "Un prototipo es código desechable que responde una pregunta. La pregunta decide la forma". Hay dos ramas y elegir mal tira el prototipo entero.

Rama lógica: un HTML que se abre con doble clic

Para "¿esta lógica o este modelo de estados se siente bien?". El resultado es un único fichero HTML sin framework, sin bundler y sin servidor, que se puede mandar por correo a alguien que no programa:

1. La pregunta, escrita arriba del todo, visible en la página.
2. La lógica aislada en un módulo puro: un reducer (estado, acción) => estado, una máquina de estados, un conjunto de funciones puras o una clase con métodos claros. Sin DOM dentro. La página llama al módulo, nunca al revés.
3. El estado actual en un panel legible, actualizado tras cada clic.
4. Botones libres, uno por acción, para probar en cualquier orden, más recorridos guiados en pestañas para los casos difíciles.

Todo en lenguaje del negocio, no del código. La clave está en el punto 2: cuando el prototipo responde la pregunta, ese módulo puro se puede llevar tal cual al código real.

Rama UI: varias variantes en la misma ruta

Para "¿cómo debería verse esto?". El resultado son varias variantes radicalmente distintas (3 por defecto, 5 como máximo) en una sola ruta, que se cambian con un parámetro ?variant= y una barra flotante abajo.

La skill prefiere con fuerza montar las variantes sobre una página que ya existe, con su cabecera, su menú y sus datos reales. Una ruta vacía es un vacío donde cualquier variante parece buena. Solo si no hay ninguna página donde encaje crea una ruta nueva con "prototype" en el nombre.

Reglas comunes

• Desechable desde el primer día y marcado como tal, pero junto al código donde se usará.
• Trivial de arrancar: un comando (pnpm <nombre>) o un doble clic.
• Sin persistencia salvo que la persistencia sea la pregunta, y entonces con un nombre del tipo "PROTOTYPE, bórrame".
• Sin pulir: sin tests ni manejo de errores más allá de que funcione.
• Mostrar el estado tras cada acción o cambio de variante.
• Guardarlo al terminar: la decisión validada pasa al código real, y el prototipo se guarda en una rama prototype/<nombre> fuera de main, enlazada desde el issue. Es una fuente primaria para quien venga después.

research: un agente que lee por ti

research es la skill más corta del repositorio. Lanza un agente en segundo plano con contexto limpio, así que tú sigues trabajando mientras lee. Su encargo tiene tres puntos:

1. Investigar contra fuentes primarias: documentación oficial, código fuente, especificaciones, APIs del propio proveedor. Nada de resúmenes de terceros. Cada afirmación se sigue hasta la fuente que la posee.
2. Escribir los hallazgos en un único fichero Markdown con cada afirmación citada.
3. Guardarlo donde el repositorio ya guarda ese tipo de notas, o en un sitio razonable, y decir dónde.

El resultado no sustituye a pensar: es material para llevar a grill-with-docs. La investigación alimenta la decisión; no la toma.

Cómo se combinan

Las dos responden preguntas que bloquean una decisión, pero de naturaleza opuesta: research trae hechos del exterior y prototype genera experiencia propia. Usadas en orden, se refuerzan. Un ejemplo con la newsletter que diseñamos en la sesión real de grill-me:

1. research: "¿qué límites de envío y qué webhooks de rebote tiene el plan gratuito del proveedor?". El agente lee la documentación oficial y deja un fichero con enlaces. Esto confirma o desmiente lo que el agente dijo de memoria durante el interrogatorio.
2. prototype (lógica): un HTML con la máquina de estados del número semanal (borrador, aprobado, enviado, omitido) y botones para "aprobar tarde", "cambiar un precio después de aprobar" o "dos crons a la vez". Lo puede probar alguien que no programa.
3. prototype (UI): tres variantes de la página de revisión sobre la ruta de administración real.

Las tres respuestas vuelven a grill-with-docs y de ahí a to-spec. Si un fragmento del prototipo expresa una decisión mejor que la prosa (la máquina de estados), to-spec lo puede incluir citando que viene del prototipo.

Errores frecuentes

• Elegir mal la rama. Una pregunta de lógica contestada con tres pantallas bonitas no responde nada.
• Pulir el prototipo. Si tiene tests y manejo de errores, ya no es desechable.
• Fusionar el prototipo en main. Lo que va a main es la decisión; el prototipo vive en su rama.
• Pedir a research que decida. Trae hechos citados; la decisión sigue siendo tuya.
• Aceptar fuentes secundarias. Si el fichero cita un blog en lugar de la documentación oficial, pide que lo rehaga.

Preguntas frecuentes

¿research necesita búsqueda web? Para documentación externa, sí: el agente necesita poder leer las fuentes. Para preguntas sobre tu propio código o tus dependencias instaladas, basta con leer ficheros.

¿Puedo enseñar el prototipo de lógica a un cliente? Es su propósito: un HTML sin instalación, en lenguaje del negocio.

¿Cuántas variantes de UI pido? Tres por defecto. A partir de cinco dejan de ser radicalmente distintas.

Siguiente paso

La próxima vez que discutas un modelo de estados en abstracto, pide un prototipo de lógica y pruébalo con botones. En la parte 10 de la guía vemos wayfinder y triage, las dos skills que gestionan trabajo grande y trabajo que llega de fuera.