anniebellb/lección-de-datos-narrada

Lección de datos narrada

Construye una lección como el ejemplo de referencia (con quién pasamos el día, por edad): un video narrado que se reproduce sobre un gráfico en vivo, luego una pestaña Explorar donde los estudiantes juegan con los datos. Una lección = una carpeta con index.html, lesson.json, data.json, video.json (guion gráfico), audio de narración y una pista musical opcional.

Lee primero: references/design-rules.md (apariencia aprobada, reglas de movimiento y énfasis; síguelas exactamente) y references/user-guidance.md (cómo trabajar con el usuario).

Las rutas a continuación son relativas a la carpeta de esta habilidad (${CLAUDE_SKILL_DIR}).

Con quién trabajas

Supón que el usuario no es técnico. Habla con claridad, paso a paso, y dile exactamente qué hacer clic cuando necesite algo (descargar un archivo, iniciar sesión en ElevenLabs, aprobar un guion). Nunca le pidas que edite código o JSON. Usa las guías en references/user-guidance.md.

El flujo de trabajo (con puntos de control y autoevaluaciones)

Ejecuta la autoevaluación al final de cada paso. No avances si hay FALLO.

1. Obtener los datos

• Acepta un enlace, un archivo o un PDF. Si un enlace está bloqueado (los sitios a menudo bloquean descargas automatizadas), guía al usuario para descargarlo en su navegador y compartir el archivo.
• Perfílalo: python3 scripts/profile_data.py <archivo-o-url>.

2. ¿Encaja? (díselo al usuario, siempre)

Lee los veredictos del perfilador y references/chart-chooser.md, luego dile al usuario en lenguaje sencillo:

• Encaja: "Esto funciona como ___ porque ___." Nombra la pregunta de aprendizaje que responde.
• Encaja parcialmente: qué funciona, qué falta y la compensación.
• No encaja: dilo claramente, explica por qué y describe qué datos funcionarían. No lo fuerces.

✋ Punto de control 1: tipo de gráfico y ángulo de la historia

Propón el tipo de gráfico, la pregunta de aprendizaje principal y 4–6 puntos narrativos (las cosas que el narrador señalará), cada uno vinculado a un número que calcularás. Espera la aprobación del usuario.

3. Dar forma a los datos

• Inicia la carpeta de la lección: python3 scripts/new_lesson.py --chart <tipo> --out <carpeta>.
• Escribe un script pequeño y reejecutable (en la carpeta de la lección) que convierta la fuente en data.json en el formato del gráfico (references/data-formats.md) y escriba facts.json: cada número que dirá el narrador, calculado a partir de los datos fuente, con cómo se pronunciará.
• Autoevaluación: python3 scripts/check_lesson.py <carpeta>; también verifica manualmente 2–3 valores contra la fuente (abre el archivo original y encuéntralos). Informa lo que verificaste.

4. Escribir la historia

• Escribe video.json (escenas, puntos narrativos, claves) siguiendo references/storyboard.md y el arco narrativo en design-rules §1 (gancho introductorio → cómo leer el gráfico → puntos narrativos → resumen → reflexión → "tu turno").
• Escribe el guion de narración en el estilo de ElevenLabs (references/narration.md) en narration/script.txt. Cada afirmación debe coincidir con facts.json; evita exagerar (design-rules §8).
• Completa lesson.json: título, subtítulo, etiqueta clave, descripciones de grupos, notas, fuentes.

✋ Punto de control 2: aprobar el guion

Muestra el guion como texto sin formato. Ofrece opciones cuando el usuario las pida; no apliques cambios que no haya aprobado.

5. Vista previa (antes de cualquier grabación)

• Vista previa silenciosa: python3 scripts/estimate_timing.py <carpeta>/video.json --out <carpeta>/narration/narration.words.json luego python3 scripts/time_storyboard.py <carpeta>/video.json <carpeta>/narration/narration.words.json.
• Sirve y ábrelo: python3 scripts/devserver.py 8123 (desde la carpeta superior a la lección), luego http://localhost:8123/<leccion>/.
• Autoevaluación (navegador): sigue references/self-checks.md: capturas de pantalla en cada punto narrativo, nada superpuesto, sin errores de consola, cada elemento nombrado resaltado en su palabra.

6. Narración y música (necesita la cuenta de ElevenLabs del usuario)

• Guía al usuario para iniciar sesión (user-guidance.md → ElevenLabs). Configuración: voz Quentin – Narrador y Educador, Eleven v4, Estabilidad ≈ 80%, Inglés; todo el guion en una toma. Guarda como narration/narration.mp3.
• ¿No tienes ElevenLabs? Ofrece el marcador de posición gratuito: python3 scripts/placeholder_voice.py <carpeta> (Mac).
• Sincroniza las palabras: python3 scripts/align_narration.py <carpeta>/narration/narration.mp3 --out <carpeta>/narration/narration.words.json, luego time_storyboard.py de nuevo. Apunta a ≥ 99% de palabras coincidentes.
• Música (opcional, ElevenLabs Music, instrumental, tranquila, ~2 min): prepárala con prep_music.py; si el video es más largo que la pista, extiéndela con find_loop.py + extend_music.py (nunca dejes que termine o se repita debajo del narrador).
• Autoevaluación: check_lesson.py (duraciones de audio, datos) + una reproducción completa en el navegador.

✋ Punto de control 3: revisión conjunta

Guía al usuario a través de la lección terminada: qué observar, cómo probar Explorar. Realiza los cambios que solicite, volviendo a ejecutar las autoevaluaciones después de cada uno.

7. Publicar (opcional)

Guíalos a través de GitHub Pages o cualquier host estático (user-guidance.md → Publicación). La carpeta de la lección es autocontenida.

Reglas de autoevaluación (siempre)

• Ejecuta scripts/check_lesson.py después de los pasos 3, 4, 5, 6 y después de cada revisión.
• Verifica en el navegador después de cualquier cambio visual: toma capturas de pantalla en los momentos narrados y compáralas con el guion gráfico. Di lo que verificaste.
• Recalcula cada número narrado a partir de los datos fuente; nunca escribas un número de memoria.
• Si algo falla, arréglalo y vuelve a verificar antes de decirle al usuario que está listo.

Archivos de referencia

Archivo	Úsalo para
references/design-rules.md	Apariencia, movimiento, énfasis, narración, sincronización, música, honestidad de datos
references/chart-chooser.md	Qué gráfico para qué pregunta; criterios de ajuste
references/data-formats.md	Los cuatro formatos de data.json
references/storyboard.md	video.json: escenas, puntos narrativos, claves por tipo de gráfico, facts.json
references/narration.md	Estilo del guion, configuración de ElevenLabs, sincronización, música
references/self-checks.md	Qué verificar en cada paso
references/user-guidance.md	Guías en lenguaje sencillo para el usuario
references/chart-interface.md	Añadir un nuevo tipo de gráfico