video-qa

¿Qué hace video-qa?

Evalúa una demo MP4 comparándola con su storyboard previsto y devuelve la lista de verificación con marcas de tiempo que escribiría un revisor humano exigente. Dos capas: una sonda determinista (ffmpeg/ffprobe/node — detección mecánica, sin razonamiento del modelo) y un subagente de análisis fresco que razona sobre el informe JSON compacto de la sonda más un conjunto limitado de fotogramas extraídos comparándolos con el guion.

Regla estricta: el análisis SIEMPRE se ejecuta en un subagente fresco

El invocador (tú, en el hilo principal) hace el mínimo:

1. Localizar las entradas.
2. Ejecutar el script de la sonda.
3. Crear un subagente independiente fresco (la herramienta Agent) para realizar el análisis.
4. Reenviar la lista de incidencias del subagente al usuario.

Nunca leas los fotogramas extraídos ni razones sobre el informe tú mismo en el hilo principal. El objetivo es el aislamiento de tokens: un video de 5 minutos produce ~50 fotogramas y un informe JSON grande; razonar sobre ellos cuesta decenas de miles de tokens en imágenes + análisis. Si eso llega al contexto del invocador, envenena el resto de la sesión. El subagente lo absorbe y solo devuelve la lista breve de incidencias. Esto no es opcional ni "cuando sea conveniente" — cada invocación de video-qa hace la transferencia. Consulta references/handoff.md.

Paso 1 — Recopilar entradas

Necesitas:

• Ruta del video — el MP4 a evaluar (el montaje final que un revisor vería).
• Storyboard / guion — las secuencias previstas en orden, expectativas de tiempo y qué debe mostrar cada segmento. Si el usuario no lo ha proporcionado, pídelo (o la incidencia o storyboard de demo-video del que proviene). No inventes secuencias.
• Tarjetas esperadas — las tarjetas guionizadas (portada, agenda, cada intersticial, resumen) en orden. Escríbelas en un archivo JSON pequeño para --cards-file: un arreglo de entradas { "label": "Portada (título + subtítulo)" } (agrega "minRead": <seg> para anular la barra de tiempo de lectura para una tarjeta más extensa). Esto impulsa la verificación determinista de tarjetas — una salida de primera clase, ya que las tarjetas son narración escrita.
• Marca — colores de tarjeta/fondo y colores de cursor/anotación, para que la sonda pueda clasificar tarjetas de marca y el subagente pueda verificar contraste. Valores predeterminados si no se especifican: pregunta; no adivines una marca.

Paso 2 — Ejecutar la sonda determinista

node ${CLAUDE_PLUGIN_ROOT}/skills/video-qa/scripts/probe.mjs \
  --video "<ruta/absoluta/al/video.mp4>" \
  --out   "<directorio-de-trabajo>/video-qa-report.json" \
  --frames-dir "<directorio-de-trabajo>/video-qa-frames" \
  --card-rgb 15,81,255 \          # el color de la tarjeta de marca como R,G,B (ej. #0F51FF)
  --cards-file "<directorio-de-trabajo>/cards.json"   # las tarjetas esperadas del storyboard, en orden

Usa un <directorio-de-trabajo> temporal (ej. bajo /tmp), no el repositorio del usuario. La sonda escribe el informe JSON y el conjunto limitado de fotogramas, e imprime la ruta del informe. Ejecuta tres pasadas de filtro de video completo (congelamiento, corte de escena, movimiento) más muestreo por escena — presupuesta ~1–1.5× la duración real del video. Ajustables (todos opcionales, con valores predeterminados sensatos incorporados): --card-tol, --demo-freeze, --annot-freeze, --card-min-read (barra de tiempo de lectura, 2.5s) y --annotate-rgb R,G,B — el color de la llamada de anotación. Cuando se proporciona, una región de silencio que contenga un anillo de anotación "mira aquí" en ese color se trata como ritmo intencional (annotated: true) y se excluye del recuento de silencios destacados en lugar de marcarse como defecto. Consulta references/detectors.md para saber qué mide cada detector y por qué los umbrales están configurados donde están.

La detección de anotaciones se limita a regiones de silencio, por lo que annotatedRegionCount: 0 NO significa "no hay anotaciones en el video". Un anillo solo se registra cuando coincide con un intervalo congelado/sostenido; si el montaje recorta el silencio (o el anillo se reproduce sobre movimiento), el anillo aún se renderiza en pantalla pero ninguna región de silencio lo contiene — el recuento es 0 por construcción. Nunca informes que faltan anotaciones basándote solo en ese número; si una secuencia está guionizada para rodear algo, confírmalo a partir de los fotogramas de ese segmento (el fotograma span-* por escena, o extrae el fotograma en la marca de tiempo de la anotación).

Verifica brevemente el resumen impreso (recuento de intervalos, regiones de silencio, recuento de fallos, recuento de fotogramas y cardCheck.countMatches) antes de hacer la transferencia. Si cardSpans es 0, el --card-rgb probablemente sea incorrecto — corrígelo y vuelve a ejecutar, de lo contrario cada tarjeta se leerá como ui y la clasificación de congelamiento/silencio/tarjeta no tendrá sentido. Si cardCheck muestra una discrepancia en el recuento, eso es un hallazgo real (una tarjeta faltante o extra), no un error de la sonda — deja que el subagente lo confirme con los fotogramas.

Paso 3 — Transferir al subagente de análisis

Crea un subagente fresco con la herramienta Agent (subagent_type: general-purpose). Construye su prompt a partir de references/analysis-prompt.md, sustituyendo:

• {{REPORT_PATH}} → la ruta --out del paso 2.
• {{FRAMES_DIR}} → la ruta --frames-dir.
• {{OUT_FINDINGS}} → una ruta de archivo de hallazgos que leerás (ej. <directorio-de-trabajo>/video-qa-findings.md).
• {{STORYBOARD}} → las secuencias previstas del paso 1, textualmente.
• {{BRANDING}} → las reglas de marca del paso 1.

Indica al subagente — como instrucción explícita en su prompt inicial — que ESCRIBA sus hallazgos en {{OUT_FINDINGS}} como el último paso de su turno. Leer ese archivo es la ruta de recuperación confiable: el mensaje de texto final de un agente creado no siempre se entrega al invocador, y los seguimientos de "envíame tus hallazgos" a menudo llegan a un agente inactivo que no volverá a participar. El archivo contiene solo la lista de incidencias (sin fotogramas), por lo que no rompe el aislamiento de tokens. El subagente aún lee el informe + fotogramas y razona secuencia por secuencia; solo persiste el resultado donde puedas leerlo.

Paso 4 — Reenviar

Lee el archivo de hallazgos ({{OUT_FINDINGS}}) y pasa la lista de incidencias al usuario tal cual (ya está en el formato de entrega). No agregues nada de tu propio razonamiento sobre los fotogramas — nunca los viste, por diseño. Si el usuario lo quiere como un artefacto HTML con marca, eso es un seguimiento separado.

Verifica puntualmente los elementos "no se pudo determinar" antes de tratarlos como defectos. La sonda muestrea un conjunto limitado de fotogramas (decenas, no cada fotograma), por lo que una secuencia que realmente ocurrió puede caer entre muestras y devolverse como "no se pudo determinar" o una bandera "parece salto de página / no se muestra" — una brecha de muestreo, no una ausencia real. Estos son los hallazgos más baratos de equivocarse. Para cada uno de esos elementos, extrae los pocos fotogramas en la marca de tiempo exacta en la que debería ocurrir (ej. ffmpeg -ss <t> -i video.mp4 -frames:v 1 …) y confirma directamente antes de informarlo como defecto. Informa solo lo que el video completo realmente carece; degrada las secuencias confirmadas como presentes a ✅ con una nota de que se verificaron fuera del conjunto muestreado.

Qué detecta (y qué no puede)

• Confiable, mecánico: silencios / regiones de UI congeladas (exploración de densidad de movimiento), estructura de escenas/segmentos, clasificación de tarjeta de marca vs UI, clústeres de fallos (refrescos erráticos / parpadeo de salto de página), estadísticas generales de contraste/luminosidad.
• Razonamiento del subagente sobre fotogramas limitados: UI de plomería fuera del guion (paneles de administración, registros, trazas de error) — incluyendo destellos breves de inicio de sesión/carga/vacío/administrador entre secuencias y recargas a medio segmento, que se tratan como defectos de pulido, no transiciones aceptables; sobreedición / cortes duros (el recorte de silencio eliminó movimiento real — cursor teletransportándose sin desplazamiento, transición de página que saltó bruscamente, corte a media acción) que se leen como falsos; secuencias faltantes/incorrectas; estilo de navegación como verificación de primera clase (navegación a través del producto vs salto de página a una página profunda); tarjetas juzgadas por si impactan (duración legible, no socavadas por un vecino contradictorio/vacío) en lugar de solo presencia, con tarjetas de portada vs agenda distinguidas por contenido; datos en pantalla incorrectos (recuentos, filas rotas); anotaciones faltantes; trampas de marca/contraste.
• Puntos ciegos: un título en pantalla faltante durante una región por lo demás activa (la animación de carga se lee como movimiento), y si una acción realmente falló o se editó fuera de cuadro. El subagente los señala como "no se pudo determinar".

references/validation-notes.md registra cómo la habilidad puntuó frente a la lista dorada revisada por humanos del fixture de referencia.