video-qa

O que video-qa faz?

Analisa um MP4 de demonstração contra seu storyboard pretendido e retorna a lista de verificação com timestamps que um revisor humano afiado escreveria. Duas camadas: uma sonda determinística (ffmpeg/ffprobe/node — detecção mecânica, sem raciocínio de modelo) e um subagente de análise fresco que raciocina sobre o relatório JSON compacto da sonda + um conjunto limitado de quadros extraídos em relação ao script.

Regra rígida: a análise SEMPRE executa em um subagente fresco

O chamador (você, na thread principal) faz o mínimo:

1. Localiza as entradas.
2. Executa o script da sonda.
3. Cria um subagente independente fresco (a ferramenta Agent) para fazer a análise.
4. Repassa a lista de problemas do subagente de volta ao usuário.

Nunca leia os quadros extraídos ou raciocine sobre o relatório você mesmo na thread do chamador. O ponto principal é o isolamento de tokens: um vídeo de 5 minutos produz ~50 quadros e um relatório JSON grande; raciocinar sobre eles custa dezenas de milhares de tokens de imagens + análise. Se isso cair no contexto do chamador, envenena o resto da sessão. O subagente absorve isso e retorna apenas a lista curta de problemas. Isso não é opcional ou "quando conveniente" — toda invocação de video-qa faz a transferência. Veja references/handoff.md.

Passo 1 — Coletar entradas

Você precisa:

• Caminho do vídeo — o MP4 a ser analisado (a versão final/montagem que um revisor assistiria).
• Storyboard / script — os beats pretendidos em ordem, expectativas de tempo e o que cada segmento deve mostrar. Se o usuário não forneceu um, peça (ou o issue ou storyboard de demo-video de onde veio). Não invente beats.
• Cartões esperados — os cartões scriptados (capa, agenda, cada interstitial, recapitulação) em ordem. Escreva-os em um pequeno arquivo JSON para --cards-file: um array de entradas { "label": "Capa (título + subtítulo)" } (adicione "minRead": <seg> para substituir a barra de tempo de leitura para um cartão mais extenso). Isso direciona a verificação cruzada determinística de cartões — uma saída de primeira classe, já que cartões são narração autorada.
• Marca — cores do cartão/fundo e cores do cursor/anotação, para que a sonda possa classificar cartões de marca e o subagente possa verificar contraste. Padrões se não especificados: pergunte; não adivinhe uma marca.

Passo 2 — Executar a sonda determinística

node ${CLAUDE_PLUGIN_ROOT}/skills/video-qa/scripts/probe.mjs \
  --video "<caminho/absoluto/para/video.mp4>" \
  --out   "<dirtrabalho>/video-qa-report.json" \
  --frames-dir "<dirtrabalho>/video-qa-frames" \
  --card-rgb 15,81,255 \          # a cor do cartão da marca como R,G,B (ex. #0F51FF)
  --cards-file "<dirtrabalho>/cards.json"   # os cartões esperados do storyboard, em ordem

Use um <dirtrabalho> scratch/temp (ex. em /tmp), não o repositório do usuário. A sonda escreve o relatório JSON e o conjunto limitado de quadros, e imprime o caminho do relatório. Ela executa três passagens de filtro no vídeo completo (congelamento, corte de cena, movimento) mais amostragem por cena — planeje ~1–1.5× a duração real do vídeo. Ajustáveis (todos opcionais, com padrões sensíveis embutidos): --card-tol, --demo-freeze, --annot-freeze, --card-min-read (barra de tempo de leitura, 2.5s) e --annotate-rgb R,G,B — a cor de destaque da anotação. Quando fornecido, uma região de silêncio contendo um anel de anotação "olhe aqui" nessa cor é tratada como ritmo intencional (annotated: true) e mantida fora da contagem principal de silêncio, em vez de sinalizada como defeito. Veja references/detectors.md para o que cada detector mede e por que os limites estão onde estão.

A detecção de anotações é limitada a regiões de silêncio, então annotatedRegionCount: 0 NÃO significa "sem anotações no vídeo". Um anel só é registrado quando coincide com um intervalo congelado/sustentado; se a montagem corta o silêncio (ou o anel toca durante movimento), o anel ainda aparece na tela, mas nenhuma região de silêncio o carrega — a contagem é 0 por construção. Nunca relate anotações como ausentes apenas por esse número; se um beat deve anotar algo programado, confirme a partir dos quadros daquele segmento (o quadro span-* por cena, ou extraia o quadro no timestamp da anotação).

Verifique o resumo impresso (contagem de spans, regiões de silêncio, contagem de falhas, contagem de quadros e cardCheck.countMatches) antes de transferir. Se cardSpans for 0, o --card-rgb provavelmente está errado — corrija e execute novamente, caso contrário, todo cartão será lido como ui e a classificação congelamento/silêncio/cartão será sem sentido. Se cardCheck mostrar uma incompatibilidade de contagem, isso é um achado real (um cartão ausente ou extra), não um erro da sonda — deixe o subagente confirmar com os quadros.

Passo 3 — Transferir para o subagente de análise

Crie um subagente fresco com a ferramenta Agent (subagent_type: general-purpose). Monte seu prompt a partir de references/analysis-prompt.md, substituindo:

• {{REPORT_PATH}} → o caminho --out do passo 2.
• {{FRAMES_DIR}} → o caminho --frames-dir.
• {{OUT_FINDINGS}} → um caminho de arquivo de achados que você lerá (ex. <dirtrabalho>/video-qa-findings.md).
• {{STORYBOARD}} → os beats pretendidos do passo 1, na íntegra.
• {{BRANDING}} → as regras de marca do passo 1.

Diga ao subagente — como uma instrução explícita em seu prompt inicial — para ESCREVER seus achados em {{OUT_FINDINGS}} como a última etapa de sua vez. Ler esse arquivo é o caminho de recuperação confiável: a mensagem de texto final de um agente criado nem sempre é entregue ao chamador, e pings de acompanhamento "envie-me seus achados" frequentemente caem em um agente ocioso que não reengajará. O arquivo contém apenas a lista de problemas (sem quadros), então não quebra o isolamento de tokens. O subagente ainda lê o relatório + quadros e raciocina beat por beat; apenas persiste o resultado onde você pode lê-lo.

Passo 4 — Repassar

Leia o arquivo de achados ({{OUT_FINDINGS}}) e passe a lista de problemas de volta ao usuário como está (já é o formato final). Não adicione nada do seu próprio raciocínio sobre os quadros — você nunca os viu, por design. Se o usuário quiser como um artefato HTML com marca, isso é um acompanhamento separado.

Verifique itens "não foi possível determinar" antes de tratá-los como defeitos. A sonda amostra um conjunto limitado de quadros (dezenas, não todos os quadros), então um beat que genuinamente aconteceu pode cair entre amostras e retornar como "não foi possível determinar" ou uma bandeira "parece que pulou página / não mostrado" — uma lacuna de amostragem, não uma ausência real. Esses são os achados mais baratos de errar. Para cada item desse tipo, extraia alguns quadros no timestamp exato em que deveria ocorrer (ex. ffmpeg -ss <t> -i video.mp4 -frames:v 1 …) e confirme diretamente antes de relatá-lo como defeito. Relate apenas o que o vídeo completo realmente não tem; rebaixe beats confirmados como presentes para ✅ com uma nota de que foi verificado fora do conjunto amostrado.

O que ele captura (e o que não pode)

• Confiável, mecânico: silêncio / regiões de UI congeladas (varredura de densidade de movimento), estrutura de cena/segmento, classificação de cartão de marca vs UI, clusters de falhas (atualização perdida / flicker de pulo de página), estatísticas grosseiras de contraste/luma.
• Raciocínio do subagente sobre quadros limitados: UI de encanamento fora do script (painéis de administração, logs, rastros de erro) — incluindo flashes breves de login/carregamento/vazio/admin entre beats e recarregamentos no meio do segmento, que são tratados como defeitos de polimento, não transições aceitáveis; cortes bruscos / over-editing (o corte de silêncio removeu movimento real — cursor teletransportando sem deslocamento, transição de página cortada abruptamente, corte no meio de uma ação) que parecem falsos; beats ausentes/errados; estilo de navegação como verificação de primeira classe (navegando pelo produto vs pulo de página para uma página profunda); cartões julgados se funcionam (duração legível, não prejudicado por vizinho contraditório/vazio) em vez de apenas presença, com cartões de capa vs agenda distinguidos por conteúdo; dados na tela errados (contagens, linhas quebradas); anotações ausentes; armadilhas de marca/contraste.
• Pontos cegos: uma legenda na tela ausente durante uma região ativa (animação de carregamento é lida como movimento), e se uma ação genuinamente falhou vs foi editada fora do quadro. O subagente identifica esses como "não foi possível determinar".

references/validation-notes.md registra como o skill se saiu contra a lista dourada revisada por humanos do fixture de referência.