/video-new
Escribe, antes de construir nada, qué debe explicar el video y qué puede afirmar, y consigue que el revisor firme ambas cosas. Luego detente.
Por qué existe: en la producción de la que provienen estas skills, 9 de 26 versiones ocurrieron porque un video no explicaba una funcionalidad que al revisor le importaba. Nadie había escrito esas funcionalidades antes de construir, así que cada una aparecía en una revisión, costaba un ciclo completo de renderizado y QA, y luego tenía que aplicarse manualmente a todos los demás videos. El posicionamiento y las afirmaciones costaron 3 versiones más de la misma manera. Dos hojas firmadas por adelantado son más baratas que cualquiera de esas rondas.
Antes de empezar
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
Encuentra el producto: la carpeta más cercana por encima del directorio actual que contenga un product.yaml. Si no hay, dile al usuario que ejecute /product-new primero (no puedes ejecutarlo tú: lo invoca el usuario). Lee product.yaml, kit/RULES.md y el BRIEF de cualquier video hermano en videos/: la matriz de cobertura y las afirmaciones de un hermano son el mejor punto de partida, y el reparto debe mantenerse idéntico entre videos.
El id del video proviene del argumento (minúsculas, dígitos, guiones). Si videos/<video>/ existe, detente: un video existente avanza con /video-review, nunca empezando de nuevo.
1. Pregunta para qué es el video
Un mensaje, como máximo cuatro preguntas, cada una con un valor por defecto propuesto:
- Quién lo ve y dónde se publica (pitch deck, un tour rápido del producto, página de documentación, onboarding, bucle de aterrizaje).
- Qué debe creer o ser capaz de hacer el espectador después (una frase).
- Duración aproximada (por defecto: pitch 90 s, tour 30 s, documentación 120 s, tutorial 240 s, bucle 15 s). Un tour es un pitch recortado a una o dos funcionalidades: misma apertura, pantalla final y bloqueo, menos capítulos. Elígelo cuando el revisor diga "tour rápido" o pida menos de 45 s.
- Qué funcionalidades le importan más al revisor. Pídele sus nombres, y pregunta cuáles deben mostrarse en funcionamiento y no solo mencionarse.
2. Crea la carpeta
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/video-new/scripts/new_video.py" <directorio_producto> <video> \
--format <formato> [--title "<título>"] [--duration <s>]
Copia _template/video, completa el frontmatter del BRIEF (título, video, formato, duración, idioma y revisor desde product.yaml, versión 1) y deja ambas firmas vacías. Rechaza un id duplicado.
3. Escribe las tres hojas
Lee references/sheets.md para conocer el formato de cada hoja y ejemplos de filas antes de escribir.
- BRIEF.md: intención (cita las palabras del usuario), audiencia, los capítulos propuestos, notas con cada nombre y número ficticios que usará el video (del reparto del producto, nunca nuevos sin preguntar), y una entrada de changelog vacía para v1.
- COVERAGE.md: una fila por funcionalidad con "¿debe explicarse en pantalla? sí/no", el capítulo que la explica y la prueba (lo que ve el espectador). Una funcionalidad que solo se nombra en la pantalla final no está cubierta: ese es exactamente el vacío que costó más versiones. Incluye las partes configurables (ajustes, disparadores incluidos los programados, traspaso, seguimientos) porque eran las funcionalidades que los revisores seguían pidiendo después.
- CLAIMS.md: la línea de posicionamiento (de
product.yaml, nunca de un documento de marketing), las frases a evitar (never_saymás cualquier cosa que añada el usuario), cada afirmación que la narración quiera hacer y necesite aprobación, los eslóganes aprobados y los nombres canónicos del producto frente a sus cadenas heredadas.
Verifica cada afirmación y funcionalidad contra lo que puedas ver en sources/ y la documentación. Si el producto no hace algo que el usuario pidió, dilo con una pregunta cerrada y una opción recomendada ("mostrar solo lo que existe" suele ser el valor por defecto correcto). No incluyas en la matriz una funcionalidad que el código no pueda respaldar.
4. Propón los capítulos
Añade la tabla de capítulos a BRIEF.md. Una idea por capítulo, un encuadre por capítulo, cada funcionalidad "debe explicarse" asignada a un capítulo. Abre con contexto (el nombre del producto y una línea sobre qué es), nunca dentro de la interfaz. Encuadra toda la página a 1x por defecto; los zooms profundos fueron rechazados dos veces en la producción original. Termina con amplitud (qué más hace el producto), luego el bloqueo.
5. Detente y pide las firmas
Muéstrale al usuario, en un mensaje:
- La matriz de cobertura (las filas "sí") y la tabla de capítulos.
- La línea de posicionamiento, las afirmaciones que necesitan aprobación y el eslogan propuesto.
- Como máximo tres decisiones cerradas, cada una con un valor por defecto (por ejemplo, el eslogan, un nombre del reparto, omitir una funcionalidad). Di qué significa el silencio: el valor por defecto.
Luego pídele al revisor que firme. O bien escribe su nombre en coverage_signed_by y claims_signed_by en BRIEF.md él mismo, o te dice con sus propias palabras que firmes en su nombre, y entonces ejecutas:
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/video-new/scripts/sign.py" <directorio_video> \
--coverage "<nombre del revisor>" --claims "<nombre del revisor>"
Nunca firmes por iniciativa propia, nunca firmes porque las hojas "parezcan completas", y nunca firmes con un nombre que el revisor no haya dado. La firma es la declaración del revisor de que la matriz es contra lo que juzgará el video. sign.py rechaza una matriz vacía o una línea de posicionamiento faltante; sin banderas solo muestra el estado.
No construyas, renderices, grabes narración ni despaches subagentes aquí, incluso si el usuario firma en el mismo mensaje. La construcción es /video-build, escrito por el usuario. Esta separación es lo que evita que el agente inicie una construcción costosa sobre un briefing sin firmar.
Informe
| Elemento | Valor |
|---|---|
| Video | videos/<video>/, formato, duración objetivo |
| Cobertura | N funcionalidades a explicar en pantalla, M solo listadas, capítulos |
| Afirmaciones | posicionamiento, afirmaciones pendientes de aprobación |
| Decisiones | hasta tres preguntas cerradas y sus valores por defecto |
| Firmas | sin firmar (o firmado por quién) |
Siguiente, una vez firmado: /video-build <video>.