demo-script

Habilidad Demo Script

Crea guiones estructurados para videos de demostración explorando el producto en vivo y coescribiendo con el usuario.

Por qué existe

Los buenos videos de demostración necesitan buenos guiones. Las malas demos divagan, saltan partes importantes o avanzan demasiado rápido. Esta habilidad produce un guion preciso y revisable que /record-demo puede ejecutar automáticamente.

Flujo de trabajo

Etapa 1: Brief

Recopila contexto del usuario:

Obligatorio:

• Qué producto/característica demostrar
• URL de destino (staging/producción)
• ¿Quién es la audiencia? (prospectos, usuarios existentes, desarrolladores, equipo interno)

Opcional (preguntar si no se proporciona):

• Flujo específico a mostrar (ej. "crear un caso de prueba con pasos y resultados esperados")
• Tono (profesional, casual, técnico, marketing)
• Duración objetivo (30s, 1min, 3min, 5min)
• Puntos clave a enfatizar
• Cosas a evitar/saltar

Suposiciones por defecto si no se especifican:

• Audiencia: usuarios prospectos evaluando el producto
• Tono: profesional pero accesible
• Duración: 1-2 minutos
• Resolución: 1920x1080

Etapa 2: Exploración del Producto

Usa las herramientas del navegador Playwright para explorar la interfaz de usuario real del producto.

Esto es crítico — no adivines cómo se ve la interfaz. Navega realmente por ella:

1. Abre la URL de destino en el navegador
2. Toma capturas de pantalla de cada página/pantalla relevante
3. Anota las etiquetas de botones reales, elementos de menú, campos de formulario
4. Comprende el flujo de navegación
5. Identifica los elementos de la interfaz por sus selectores reales

Ejemplo de flujo de exploración:
  → Navegar a la URL de la aplicación
  → Captura de pantalla del panel principal
  → Hacer clic en la característica objetivo
  → Captura de pantalla de cada cambio de estado
  → Anotar selectores exactos para todos los elementos interactivos
  → Verificar estados de carga, animaciones, modales

¿Por qué explorar primero?

• Nombres de selectores reales (no adivinados que fallarán durante la grabación)
• Narración precisa que coincida con lo que está en pantalla
• Descubrir el flujo natural (quizás hay un paso que el usuario olvidó mencionar)
• Detectar problemas potenciales (muros de autenticación, cargas lentas, estados vacíos)

Autenticación:

• Si la aplicación requiere inicio de sesión, pide al usuario credenciales o una sesión preautenticada
• Alternativamente, usa un entorno de staging con datos de prueba
• Nota: guarda cookies/sesión para la fase de grabación

Etapa 3: Redacción del Guion

Genera un guion estructurado en formato JSON con arrays de metadata y scenes.

Para el esquema JSON completo, referencia de acciones y estilos de resaltado, consulta references/script-format.md.

Etapa 4: Revisión e Iteración

Presenta el guion al usuario en un formato legible (NO JSON en bruto). Fórmatealo así:

🎬 Demo Script: "Creando tu primer caso de prueba"
Duración: ~90 segundos | Audiencia: Usuarios prospectos

━━━ Escena 1: Apertura — Vista general del panel ━━━
  → Navegar a /dashboard
  🎙️ "Bienvenido a OneTest. Vamos a crear tu primer caso de prueba."
  ⏸️ Pausa de 2s

━━━ Escena 2: Navegar a Casos de Prueba ━━━
  → Clic: elemento del menú lateral "Casos de Prueba"
  🎙️ "Abre la sección de Casos de Prueba desde el menú lateral."
  ✨ Resaltar: elemento del menú lateral (pulso)
  ⏸️ Pausa de 1.5s

━━━ Escena 3: Crear nuevo caso de prueba ━━━
  → Clic: botón "Crear"
  🎙️ "Haz clic en Crear para iniciar un nuevo caso de prueba."
  ✨ Resaltar: botón Crear (brillo)
  ⏸️ Pausa de 2s

  → Escribir en título: "Iniciar sesión con credenciales válidas"
  🎙️ "Asigna un título descriptivo."
  ⏸️ Pausa de 1s

  → Escribir en descripción: "Verificar que los usuarios puedan iniciar sesión..."
  🎙️ "Añade una descripción clara de lo que verifica este caso de prueba."
  ⏸️ Pausa de 1.5s

━━━ Escena 4: Cierre ━━━
  → Esperar 2s (mantener en pantalla final)
  🎙️ "Y eso es todo — tu primer caso de prueba está listo."
  ⏸️ Pausa de 1.5s

Total estimado: ~90 segundos

Iterar con el usuario:

• "¿Quieres añadir/eliminar alguna escena?"
• "¿El ritmo debería ser más rápido o más lento?"
• "¿Cambiarías algún texto de narración?"
• "¿Quieres reordenar algo?"

Etapa 5: Guardado y Entrega

Una vez aprobado:

1. Guarda el guion JSON en workspace/<date>/demo-script-<name>.json
2. Guarda la versión legible en workspace/<date>/demo-script-<name>.md
3. Dile al usuario: "¡Guion listo! Ejecuta /record-demo para grabarlo, o puedo iniciar la grabación ahora."

Referencia de Acciones del Guion

10 acciones compatibles: navigate, click, type, select, scroll, hover, wait, screenshot, drag, keyboard.

5 estilos de resaltado: pulse, glow, arrow, dim-others, zoom (inyectados mediante CSS/JS).

Referencia completa con campos y ejemplos en references/script-format.md.

Pautas de Narración

Buena narración:

• Frases cortas (menos de 15 palabras)
• Tiempo presente, voz activa ("Haz clic en Crear" no "Vamos a hacer clic en el botón Crear")
• Describe qué está sucediendo Y por qué ("Añade una descripción para que tu equipo sepa qué probar")
• No narres lo obvio ("Estoy moviendo el cursor hacia..." — no)
• Ajusta la pausa a la longitud de la narración (narración más larga = pausa más larga)

Reglas de ritmo:

• Primera escena: pausas más largas (el espectador se orienta)
• Escenas intermedias: pausas moderadas
• Última escena: mantener 2-3 segundos en el estado final
• Después de escribir: pausa corta para que el espectador lea
• Después de navegación de página: esperar a que cargue + 1s para que el espectador explore

Tono según la audiencia:

• Prospectos: enfocar en beneficios, mantener sencillo, evitar jerga
• Desarrolladores: se pueden usar términos técnicos, mostrar configuración, mencionar APIs
• Interno: puede ser más casual, referenciar convenciones del equipo

Consejos para Grandes Demos

1. Empieza con datos — No hagas una demo en una aplicación vacía. Asegúrate de que existan datos de prueba.
2. Muestra el camino feliz — Guarda los casos extremos para la documentación, no para las demos.
3. Una característica por video — Video enfocado de 90 segundos > recorrido de 10 minutos.
4. Termina en el resultado — Muestra la cosa creada/completada, no un menú.
5. Nombra las cosas de forma realista — "Iniciar sesión con credenciales válidas" > "Prueba 1".
6. Limpia la interfaz — Cierra pestañas innecesarias, oculta herramientas de desarrollo, usa un perfil de navegador limpio.