Prototipo trazable

La fase 3 del workflow: validar el PRD (Product Requirements Document) inicial con los stakeholders mediante un prototipo navegable antes de preparar la construcción. El prototipo no es un entregable decorativo — es el mecanismo de validación que evita construir sobre definiciones equivocadas, y al aprobarse se convierte en la referencia visual canónica del producto.

Por qué un prototipo y no código

Un PRD se valida mal leyéndolo: los stakeholders no leen documentos largos y aprueban cosas que no entendieron. Un prototipo navegable les muestra exactamente lo que el PRD describe. Cambiar el prototipo y el PRD en esta fase cuesta horas; cambiar código de producción cuesta sprints.

Propiedades del prototipo

1. No funcional: navegable, con datos de ejemplo. No tiene backend ni lógica real.
2. Trazable al PRD: cada bloque de la UI (interfaz de usuario) declara el ID del requisito que lo define (RF-2), no un número de sección — así la referencia sobrevive a la partición del PRD en F3.4.
3. Comentable: los stakeholders pueden dejar feedback por bloque sin fricción.
4. Un solo archivo, autónomo: un prototipo es un .html con todo adentro —pantallas, estilos y andamiaje—. Se publica como sitio estático o se manda por correo, y la recolección de feedback no requiere que nadie esté presente.
5. Un solo artefacto para las dos audiencias: un switch de modo decide si se ve anotado (para validar) o como producción (para mostrar). No hay dos versiones que mantener.

Un archivo, dos modos

Un solo archivo

Un prototipo es un archivo HTML con las pantallas, el CSS del producto y el andamiaje pegados inline. La navegación entre pantallas es cliente —mostrar y ocultar secciones—, no enlaces a otros archivos. Las razones son prácticas:

• Se entrega, no se despliega. Doble clic desde el disco, adjunto en un correo, subido a cualquier carpeta compartida. Un stakeholder que no sabe qué es un servidor lo abre igual.
• No hay rutas que romper. Mover o renombrar el archivo no rompe nada.
• El feedback queda completo. Los comentarios se guardan por prototipo, no por página: un prototipo repartido en varios archivos produce exports parciales, que es la peor forma de perder feedback —sin darse cuenta—.

Si el archivo crece hasta volverse difícil de editar (referencia: más de ~15 pantallas), se parte por área funcional en archivos igualmente autónomos, declarando el mismo identificador de proyecto para que el feedback siga junto. Es la excepción, no el punto de partida.

Dónde vive el prototipo

Un prototipo es el producto del cliente antes de existir: sus pantallas, sus reglas y las dudas abiertas sobre ellas. Es material confidencial del mismo grado que initial-references/ y se trata igual.

• No se versiona en un repositorio público ni se adjunta a un issue o a un PR abierto.
• Si se publica como sitio estático —a veces es la forma más simple de que un stakeholder lo abra— va en una URL no adivinable y fuera de los buscadores: <meta name="robots" content="noindex, nofollow"> en el archivo y, si la plataforma lo permite, la cabecera X-Robots-Tag: noindex. Con contraseña, mejor.
• Se apaga cuando la fase cierra. Un prototipo aprobado y olvidado en una URL viva es una filtración sin fecha de caducidad.
• Los datos de ejemplo son inventados. Nombres, documentos de identidad, correos y montos reales no entran al prototipo aunque estén en initial-references/: no aportan nada a la validación y viajan con el archivo a donde el archivo vaya.

El switch de modo

El mismo archivo sirve a dos audiencias sin mantener dos versiones:

El modo arranca encendido: en la fase 3 la audiencia es quien viene a validar, y un mecanismo de feedback que hay que descubrir no se usa. El estado se recuerda por visitante.

Los controles viven en un marco —una barra propia del prototipo— que nunca se confunde con el producto. Ahí van el switch, el contador de comentarios, el export y los selectores que el prototipo declare (rol, fase del flujo, escenario). Con el modo apagado, el marco sigue; lo que desaparece es toda anotación sobre el lienzo. Regla dura: con el modo apagado nada del andamiaje se filtra al lienzo —ni insignias, ni notas, ni resaltes—; si se filtra, el prototipo deja de poder mostrarse como producto.

Dirección de diseño y calidad visual

El prototipo se convierte en la referencia visual canónica del producto (ver cierre de fase): de él se consolida el design system. Por eso no puede verse improvisado — desde el primer prototipo se construye con criterio de diseño profesional, no como wireframe descartable.

Esto no contradice el principio de no sobre-invertir antes de validar: la calidad visual no es inversión funcional. Un prototipo estático bien diseñado cuesta casi lo mismo que uno feo cuando lo construye un agente UX/UI (experiencia / interfaz de usuario) con criterio y una skill de diseño — y el retorno es doble: los stakeholders aprueban lo que entienden, y la referencia canónica nace sólida.

Dirección de diseño ligera (antes de maquetar)

Antes de construir pantallas, el agente UX/UI fija una dirección de diseño ligera: paleta, tipografía, tono visual y componentes base. No es el design system completo (eso se formaliza en la fase 4, tras la aprobación) — es lo mínimo para que el prototipo se vea coherente y profesional desde el inicio.

• Si el cliente tiene manual de marca, la dirección se deriva de él: colores, tipografías, logo, tono y componentes salen de la identidad existente. El manual entra como material de initial-references/ (confidencial por defecto).
• Si no hay manual de marca, el agente UX/UI toma decisiones razonables y explícitas para tener una dirección provisional, marcada como tal para validarse con el stakeholder.

Skill de diseño

El agente UX/UI usa siempre la skill de diseño disponible (p. ej. frontend-design) antes de generar UI desde cero. Una skill de diseño sobre un modelo económico supera a un modelo caro sin ella — por eso el UX/UI se mantiene en un tier intermedio (ver Eficiencia).

El design system crece con el prototipo (no nace en fase 4)

La dirección de diseño ligera es la semilla de un design system que crece dentro del prototipo —su CSS lo va encarnando— durante toda la iteración, y que la fase 4 consolida: lo extrae a artefacto canónico (documento + tokens en código, accesibilidad por defecto). No lo crea de cero. Son tres estados de una misma cosa:

1. Semilla (aquí, antes de maquetar): paleta, tipografía, tono, componentes base.
2. Crecimiento (durante la iteración): cada ajuste confirmado refina prototipo, design system y PRD juntos (ver la Definition of Done (DoD) abajo y el comando de ciclo de ajustes).
3. Consolidación (fase 4): se extrae del prototipo aprobado al design system formal.

Si el cliente trae design system / manual de marca de entrada, ese artefacto ya es canónico desde la semilla y el prototipo se ciñe a él; la fase 4 reconcilia tokens y lo cierra, no rehace.

Mecanismo de trazabilidad granular

• Cada feature/bloque lleva un atributo de referencia con el ID estable del requisito (ej. data-prd="RF-12 · RDA automática").
• Con el modo prototipo encendido, ese atributo pinta una insignia clicable junto al componente (ej. RF-12 · F3 · decisión 8) que enlaza al requisito en el PRD.
• Se traza por ID, no por sección. Al cerrar la fase, el PRD inicial se parte en PRD de negocio y PRD técnico (F3.4): los números de sección cambian, los IDs no. Un prototipo trazado a §7.3 queda apuntando al vacío el día de la partición.
• Las dudas y aclaraciones para el cliente se agregan como pequeñas notas en los lugares adecuados del prototipo. Cada duda está también registrada en el PRD y enlazada desde el prototipo. Estas notas solo se ven con el modo encendido.

Validación de consistencia (opcional, recomendada)

Un script liviano verifica que cada ID referido en el prototipo esté definido en el PRD —en una fila de tabla o un encabezado, no en una mención de prosa, para que un ID mal escrito salga como roto— y que cada requisito del PRD tenga al menos un ancla en el prototipo. Detecta divergencias antes de que lo haga un stakeholder.

Mecanismo de feedback

Dos canales complementarios, ambos de baja fricción:

• Comentario por bloque: los comentarios se acumulan (localStorage) y se exportan como lista Markdown/JSON — ese export es literalmente el input para iterar el PRD. Todo queda en el navegador del stakeholder y no sale de ahí; también se pierde si borra los datos del sitio, así que el export se pide antes de cerrar cada ronda.
• Formulario por correo (opcional): un servicio tipo Formspree envía el feedback directo al correo, sin backend propio. Es la única pieza del andamiaje que habla con un tercero, y lo que le manda son comentarios sobre el producto del cliente: lo decide el cliente, no el equipo. Se cablea solo si lo aprueba; si no, el canal es el export del punto anterior, enviado a mano.

Definition of Done de todo cambio al prototipo

Ningún cambio al prototipo se considera terminado si no actualiza las superficies que toca:

1. (a) el HTML del prototipo
2. (b) la prosa del PRD (y su tabla de requisitos si aplica)
3. (c) la referencia de trazabilidad (data-prd)
4. (d) los specs
5. (e) el design system — cuando el ajuste toca apariencia (tokens, componentes, patrones). Si el cliente trae un design system formal, se actualiza ahí; si no, se actualiza la dirección de diseño que el prototipo encarna. Mantiene el hilo progresivo alineado.

Esta DoD se codifica como tareas en el change de OpenSpec correspondiente — así no se olvida.

El ciclo es de a un ajuste, con confirmación humana antes de propagar: se aplica el cambio solo al prototipo → el stakeholder lo confirma o lo descarta → si lo descarta, se revierte; solo si lo confirma se propaga a las demás superficies que toque (PRD, design system, trazabilidad, specs) y se reporta exactamente qué se propagó. Se limpia contexto entre ajustes. Este ciclo se opera con el comando de ciclo de ajustes (prototype-adjust).

Andamiaje reutilizable

La maquinaria de este capítulo — marco y switch de modo, insignias data-prd clicables, notas de aclaración, comentario por bloque con export Markdown/JSON, envío opcional por Formspree y el script de validación de consistencia — es idéntica entre proyectos. Argui la entrega como artefacto reutilizable en Andamiaje del prototipo: HTML/CSS/JS vanilla, sin framework, que se pega inline en el archivo del prototipo y se cablea con atributos data-prd.

Es un mecanismo, no un agente: por eso sí se distribuye (a diferencia de los agentes). Para proyectos en Claude Code se incluye además un envoltorio de skill (SKILL.md). El mecanismo es portable; la skill es solo el empaquetado.

Cierre de la fase ✋

La fase termina cuando los stakeholders aprueban el prototipo explícitamente. A partir de ahí:

• El prototipo es la referencia visual canónica del producto.
• El primer ítem del backlog (fase 4) consolida el design system que venía creciendo en el prototipo: lo extrae del prototipo aprobado a artefacto canónico —documento de referencia + tokens en código— para que no haya divergencia de apariencia entre lo que el stakeholder aprobó y lo que se entrega. No lo crea de cero; lo formaliza. (Si el cliente trajo design system de entrada, este paso reconcilia tokens y lo cierra como canónico.) El design system incluye accesibilidad por defecto (foco visible, contraste verificado en los tokens, semántica de componentes) — ver Estándares §3.
• El PRD queda sincronizado con lo aprobado (la DoD lo garantiza) y se parte en PRD de negocio y PRD técnico (F3.4), conservando los IDs de requisito.

Refinamiento: de instrumento de venta a especificación visual (opcional)

El prototipo aprobado ya hizo su trabajo: validó la definición y sirvió para vender. El refinamiento es un paso opcional que lo lleva un nivel más allá — de instrumento de validación a especificación visual ejecutable: lo que el equipo mira para construir, sin preguntas abiertas.

Cuándo se hace y cuándo se salta

Se refina cuando el costo de la ambigüedad es alto:

• El alcance quedó cerrado por contrato y cada detalle no acordado es una discusión futura.
• Construye un equipo externo o nuevo, sin el contexto de las conversaciones de la fase 3.
• El producto tiene muchos roles, estados o reglas de permiso —lo que no se ve en un camino feliz es justo donde se rompe—.
• El cliente necesita ver antes de aprobar presupuesto.

Se salta cuando el equipo que construye es el mismo que definió, el producto es chico o el cliente está disponible para resolver dudas sobre la marcha. Saltarlo no es deuda: el detalle se define igual, más tarde, dentro de cada change de la fase 5.

También es parcial por diseño: se refinan los flujos que lo justifican, no todos. Refinar todo es la trampa que este paso quiere evitar.

Qué se completa

1. Pasos intermedios de cada flujo: lo que pasa entre la pantalla inicial y la final.
2. Estados de vacío, carga y error — no solo el camino feliz.
3. Validaciones y textos reales: mensajes, etiquetas y errores tal como los va a leer el usuario. El texto es comportamiento, no relleno.
4. Permisos por rol: qué ve y qué puede hacer cada rol en cada paso.
5. Máquinas de estado como pantallas: cada estado del negocio se puede ver, no solo leer.

Umbral de “completo” por paso

Un paso está refinado cuando tiene las cinco cosas:

camino feliz · estado vacío · un error realista · permisos por rol · textos reales

“Un error realista” y no todos los errores posibles: el objetivo es acordar el patrón de error, no enumerar el catálogo.

El entregable es el acuerdo, no el prototipo más grande

Lo que queda del refinamiento no es un prototipo con más pantallas: es el acuerdo escrito de los detalles. Se registra como un change de OpenSpec por flujo, con su delta de spec — el prototipo es la cara visual de ese spec.

Esos changes quedan pendientes, no archivados. openspec/specs/ describe lo que el sistema hace hoy; un spec archivado sobre algo sin construir declararía como hecho lo que no existe y dejaría a la fase 5 sin delta que aplicar. El spec entra a specs/ cuando la fase 5 lo construye y archiva.

Por eso el refinamiento no necesita el ciclo personalizado en F4.8: el fork del schema existe desde F0.2, y el refinamiento corre solo las etapas de definición (proposal → specs → design). Las etapas que F4.8 personaliza —apply, verify, el qa con usuarios y credenciales, la separación implementador/revisor— son de construcción, y aquí no se construye.

Troceo: un change = un flujo completo

La unidad es el flujo entero —todos sus pasos, roles y escenarios—, no la pantalla suelta ni el lote de flujos. Un flujo completo es lo mínimo que se puede acordar con un stakeholder sin que queden bordes sueltos, y lo máximo que se puede revisar de una sentada.

Inventario de flujos

El refinamiento arranca con un inventario: una matriz rol × flujo × paso donde cada celda es completo · parcial · ausente. De esa matriz salen tres cosas de un golpe: el backlog de refinamiento (lo parcial y lo ausente), el estimado y el guion de la sesión con el cliente. Plantilla: Inventario de flujos.

El inventario viaja a la fase 4 junto con los changes: es el mapa de qué llega definido y qué no.

Escenarios en el prototipo

Ver estados de vacío, carga, error y permiso denegado exige poder cambiar de escenario sin tocar el código. El andamiaje lo resuelve con tres controles declarativos en el marco —Rol, Fase y Escenario—: el prototipo declara los valores, el marco pinta los selectores y cada bloque se muestra u oculta según corresponda. Es el mecanismo que hace que las cinco cosas del umbral se puedan mirar, no solo describir. Detalle en Andamiaje del prototipo.

Lo que hay que saber del refinamiento parcial

• Los flujos sin refinar no quedan fuera de nada. El backlog de la fase 4 sale de los PRDs y sigue siendo la lista completa; lo que el refinamiento hace es adelantar algunos ítems al estado de “definido al punto de poder construirse”. El resto llega a ese estado en su turno.
• La estimación queda desigual, y eso es información. Lo refinado se estima con poca varianza; lo demás carga riesgo de definición. El inventario es el mapa de esa asimetría, útil para la propuesta comercial.
• Un change puede envejecer entre que se define y se construye. Se revalida en el gate de la fase 5, contra el PRD y el prototipo vigentes.

El prototipo después del lanzamiento

Su trabajo —validar definiciones antes de construir— termina al aprobarse el prototipo y consolidarse el design system. En evolución continua (ver Las 7 fases fase 6) su rol es acotado, no fuente de verdad:

• Las fuentes de verdad post-lanzamiento son el PRD/specs (comportamiento), el design system (apariencia) y el producto/código (lo construido).
• No se actualiza con cambios chicos ni espeja lo que ya está en producción —espejear algo que se puede clicar es sobre-inversión.
• Sí se usa para maquetar trabajo nuevo, significativo y visible antes de construirlo, ahora con los componentes del design system canónico (más fidelidad, más barato, y siembra la implementación). La maquinaria de trazabilidad y feedback de este capítulo sigue aplicando a ese slice nuevo.

---

Cuando no hay UI: qué se valida en la fase 3

El prototipo es la forma que toma la fase 3 cuando el producto tiene interfaz. Lo que la fase valida siempre es la superficie observable del producto —lo que su consumidor puede ver o invocar—, y qué es esa superficie depende del producto.

Los pasos no cambian: F3.1 crea el dueño de la superficie, F3.2 la construye trazada por RF-*, F3.3 la itera con el consumidor y cierra ✋, F3.4 parte el PRD y F3.5 refina los caminos no felices —errores por operación, límites, paginación en el borde, concurrencia e idempotencia—, con el mismo entregable: un change pendiente por unidad acordada.

El umbral de F3.3 es distinto. Un prototipo se aprueba porque el stakeholder entendió lo que vio; un contrato se aprueba cuando el consumidor puede escribir su cliente contra el mock sin preguntar nada. Es verificable, no es “lo leí y me pareció bien”.

Lo que no se traslada: el switch de modo, las insignias y el feedback por bloque son maquinaria de UI. En un contrato la trazabilidad se declara en la propia operación y el feedback es revisión más intento de integración.

Híbrido es el caso normal. Un producto con UI y con API consumida por terceros corre los dos: el prototipo se valida con el usuario de negocio, el contrato con el consumidor técnico.