Entrega de sitio de narrativa visual
Principios centrales
Preguntar claro → Hacer plan → Revisión independiente → Autoverificar → Medir y corregir → Implementar por lotes → Cada lote desplegable. Cualquier criterio de aceptación que no pueda ser verificado por script (como «no se traba» o «se ve bien») está prohibido: cada estándar de aceptación debe poder ser evaluado por un navegador headless mediante aserciones.
Este skill consta de 6 componentes:
- Este archivo: Proceso de 7 fases + lista de preguntas + plantilla de revisión + formato de reporte.
references/verify-recipes.md: 13 técnicas de medición en runtime + trampas de coordenadas/pipeline.references/pitfalls.md: 22 fallos reales (síntoma → causa raíz → corrección → regla general).references/animation-components.md: Patrones de integración de componentes canvas de terceros (clave de caché / cleanup / condiciones de montaje / verificación de pausa).references/content-sourcing.md: Los números deben tener fuente o indicar claramente que son fines didácticos (obligatorio para divulgación científica, médica, datos).assets/:long-stage.tsx+long-stage.css(estructura de tres capas del escenario largo),tokens.css(doble tema),verify-skeleton.mjs.md(esqueleto del script de verificación).
Correspondencia de qué leer al dispararse: Si se necesita integrar un componente de animación de terceros → leer animation-components; si la página tiene números o conclusiones científicas concretas → leer content-sourcing; el resto se lee en orden de fases.
Fase 1: Preguntar, no suponer
Cuando exista cualquier suposición no confirmada sobre los requisitos, está prohibido escribir código. Dibuja un árbol de decisiones pendientes; cada ronda solo pregunta las condiciones previas que ya están determinadas. Cada pregunta debe incluir una respuesta recomendada + justificación, para que el usuario pueda decir sí directamente; lo que puedas verificar por ti mismo (leer archivos, ejecutar comandos, consultar documentación) no se le pregunta al usuario.
Lista obligatoria de preguntas (en orden de dependencia, puede recortarse según el proyecto):
- ¿Cuál es el tema específico (área / subárea / ángulo de presentación)?
- ¿Para quién es? (determina densidad de jerga y tolerancia al error) — «Perspectiva del evaluador/revisor» es un requisito implícito que debe indagarse activamente: preguntar «¿Quién decide si está bien hecho?» es más efectivo que preguntar «¿Qué tan profundo escribir?».
- ¿Qué debe entender la persona al ver la página por primera vez? (una frase que defina el tono; ofrecer candidatos como «impacto numérico / interactivo con preguntas / contraste sorpresivo»).
- Fuente de los datos: real trazable / fines didácticos / mixto.
- Tono visual: inmersivo oscuro / profesional claro / alto contraste.
- Forma de entrega: landing de una página / scroll largo de múltiples capítulos / varias páginas.
- ¿Se necesita 3D? (beneficio vs. costo de verificación).
- Mejora interactiva: escenario largo / seguimiento del ratón / componentes de animación de terceros.
- Ubicación del directorio del proyecto.
- ¿Cómo incorporar los materiales de referencia proporcionados por el usuario? (integración del código fuente vs. solo referencia visual).
- URL en línea / método de despliegue.
Es normal que el usuario revise decisiones a medio camino (ej.: claro → doble tema). La tabla de decisiones debe conservar un registro de «decisión original descartada», no sobrescribir en silencio.
Fase 2: Hacer plan, esperar revisión
El plan se escribe en docs/plan-<tema>.md y se añade al repositorio. Debe incluir:
- Análisis del estado actual: al modificar un proyecto existente, cada frase debe llevar
archivo:línea; para proyectos nuevos, listar el inventario de archivos. - Tabla de decisiones D1–Dn: cada una debe explicar «por qué se eligió esto», no «pienso hacer esto».
- División en lotes: cada lote debe ser desplegable independientemente y reversible.
- Los criterios de aceptación deben poder ser evaluados mediante script: «no se traba» → «mediana del intervalo entre rAF ≤ 33ms»; «se ve bien» → «desenfoque(3px) opacidad .55 en tarjetas adyacentes».
- Indicar qué no se hará: escribir las exclusiones explícitamente para evitar que el alcance crezca durante la implementación.
Fase 3: Esperar confirmación explícita
«Mm», «bien», «ok» se consideran ambiguos, se debe reconfirmar; «tú decides» no cuenta como confirmación.
Fase 4: Revisión independiente
Enviar a un subagente con contexto completamente nuevo para que revise el plan. No solo debe ver el plan, sino que también debe recibir el código real y el script de verificación.
Estás revisando un plan que aún no se ha empezado a implementar. Tu tarea es encontrar problemas, no aprobar.
## Lectura obligatoria
- Documento del plan: <ruta>
- Código real: <raíz del proyecto>, enfocarse en <archivo>
- Herramienta de verificación: <ruta del script>
## Revisar por prioridad
1. Precisión fáctica (el valor más alto): ¿Cada `archivo:línea` es correcto? ¿Cada afirmación sobre el comportamiento existente es cierta? Si es incorrecto, refutar con la línea real del código.
2. Completitud: si afirma implementar N decisiones, verificar una por una si todas tienen tareas asignadas.
3. Contradicciones internas: ¿La sección A promete algo que la sección B prohibe?
4. Riesgos técnicos específicos: listar 3-5 puntos más propensos a errores en esta tarea.
5. Omisiones: ¿Qué cosas no están escritas en el plan y el implementador debe inventar?
6. Verificabilidad de la aceptación: ¿Cada criterio puede ser evaluado objetivamente? ¿Cuáles son ambiguos?
7. Orden de los lotes: ¿Hay lotes que dependen de lotes posteriores? ¿Hay cosas que no pertenecen a ningún lote?
## Salida
Lista numerada, cada una con: gravedad (BLOQUEANTE / MAYOR / MENOR), ubicación, qué está mal (con evidencia), cómo corregirlo.
Al final, dar conclusión: ¿se puede pasar a implementación?
No modifiques ningún archivo. No apruebes por cortesía: una revisión que no encuentra nada es una revisión fallida.
Fase 5: Las opiniones de la revisión deben verificarse personalmente
Los subagentes pueden equivocarse. Verificar una por una en el código, confirmar que sean ciertas antes de modificar. Presuponer que «una de ellas es incorrecta».
Se han observado dos resultados reales:
- Una vez, las 16 observaciones de la revisión fueron todas válidas (7 MAYOR + 9 MENOR, de las cuales 3 eran «el mecanismo de verificación en sí mismo fallaba» — aserciones siempre verdaderas o que nunca fallaban).
- Otra vez, atribuyó la detección de «idle» del componente A al componente B, y se detectó al leer el número de línea del código fuente.
Fase 6: Medición y corrección real
El agente de revisión se basa en leer código; no puede leer el tamaño en runtime, la tasa de fotogramas ni el comportamiento de composición. Utiliza un navegador headless para medir. Todos los números que se escriban en la documentación deben ser valores medidos en runtime.
Ver references/verify-recipes.md.
Fase 7: Implementación por lotes
Al final de cada lote: ejecutar verificación completa → git tag → commit. El mensaje del commit debe decir «qué se cambió, por qué, datos medidos».
Formato fijo de reporte en tres secciones:
- Qué se hizo: lista de archivos + datos medidos (no «está terminado», sino
pinTop=68.0,desviación de desplazamiento 0.0px). - Qué falta
- Qué se descubrió: ¿el plan estaba mal o el código? ¿en qué línea?
Composición mínima del sistema de verificación (medido en este proyecto: 45 aserciones / 7 pruebas unitarias)
| Capa | Herramienta | Responsabilidad |
|---|---|---|
| Tipos | tsc --noEmit | Integridad de tipos. vitest todo verde ≠ se puede construir, esbuild elimina tipos |
| Unidad | vitest run | Honestidad de datos (campo de fuente no vacío, ambos tipos deben coexistir), funciones puras |
| Runtime | scripts/verify.mjs (puppeteer-core + Chrome del sistema) | Desbordamiento de layout, contraste, tasa de fotogramas, estado de animación, ramas degradadas |
| Entrega | npm run build | El producto real se puede construir |
Las aserciones deben poder fallar. Después de escribir cada aserción, modificar el código al revés una vez para confirmar que FALLA; de lo contrario, no sabes si es siempre verdadera o realmente está probando algo.
Las aserciones que cruzan viewports deben usar setViewportSettled. page.setViewport solo garantiza que el tamaño del viewport se haya enviado, no que el reflow haya terminado; leer scrollWidth inmediatamente después puede devolver el valor anterior (antes de reducir el tamaño), lo que produce fallos intermitentes (ver references/pitfalls.md punto 21). Este tipo de problemas intermitentes solo se exponen ejecutando repetidamente las pruebas; una sola ejecución toda verde no es evidencia suficiente para la aceptación.
Conceptos erróneos comunes
| Concepto erróneo | Realidad |
|---|---|
| «Las pruebas unitarias pasan, se puede entregar» | esbuild elimina tipos; tsc reporta errores mientras vitest sigue todo verde |
| «La diferencia de capturas de pantalla puede detectar todos los cambios visuales» | El pipeline de captura headless puede no capturar el redibujado del DOM, solo la textura del canvas |
| «Esperar 500 ms de polling es suficiente» | scroll-behavior:smooth + scrub:1 son asíncronos; debe ser explícitamente instantáneo + polling explícito hasta que se cumpla la condición |
| «Responsivo es cambiar el viewport y probar una vez» | El estado de pin/touch/CDP se contamina entre pruebas; debe abrir una nueva página o un nuevo proceso de navegador |
| «Reduced-motion es desactivar animaciones» | Desactivar animaciones, pero la información no debe disminuir en absoluto; se debe afirmar que la cantidad de texto no se reduce |
Relación con otros skills
- Dirección visual / evitar el «olor a IA»:
frontend-design,design-taste-frontend - Disciplina de plan y revisión:
writing-plans,plan-sds-review - Localización de defectos:
systematic-debugging - Verificación posterior a la finalización:
verification-before-completion
Este skill solo complementa lo que ellos no cubren: la metodología de captura de datos en runtime, los fallos específicos de visualizaciones, la estructura de narrativa de scroll largo.