/video-new
Escreva, antes que qualquer coisa seja construída, o que o vídeo deve explicar e o que pode alegar, e obtenha a aprovação do revisor para ambos. Então pare.
Por que existe: na produção de onde esses skills vêm, 9 de 26 versões aconteceram porque um vídeo não explicava uma funcionalidade com a qual o revisor se importava. Ninguém havia escrito essas funcionalidades antes de construir, então cada uma surgia em uma revisão, custava um ciclo completo de renderização e QA, e depois tinha que ser aplicada manualmente em todos os outros vídeos. Posicionamento e alegações custaram mais 3 versões da mesma forma. Dois documentos assinados com antecedência são mais baratos do que qualquer uma dessas rodadas.
Antes de começar
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
Encontre o produto: a pasta mais próxima acima do diretório atual que contém um product.yaml. Se não houver, informe ao usuário para executar /product-new primeiro (você não pode executá-lo por ele: é invocado pelo usuário). Leia product.yaml, kit/RULES.md e o BRIEF de qualquer vídeo irmão em videos/: a matriz de cobertura e as alegações de um irmão são o melhor ponto de partida, e o elenco deve permanecer idêntico entre os vídeos.
O id do vídeo vem do argumento (minúsculas, dígitos, traços). Se videos/<video>/ existir, pare: um vídeo existente avança com /video-review, nunca recomeçando.
1. Pergunte para que serve o vídeo
Uma mensagem, no máximo quatro perguntas, cada uma com um valor padrão proposto:
- Quem assiste e onde é publicado (pitch deck, tour curto do produto, página de documentação, onboarding, loop de landing page).
- O que o espectador deve acreditar ou ser capaz de fazer depois (uma frase).
- Duração aproximada (padrões: pitch 90 s, tour 30 s, docs 120 s, tutorial 240 s, loop 15 s). Um tour é um pitch reduzido a uma ou duas funcionalidades: mesma abertura, tela final e lockup, menos capítulos. Escolha-o quando o revisor disser "tour rápido" ou pedir menos de 45 s.
- Quais funcionalidades são mais importantes para o revisor. Pergunte pelos nomes, e pergunte quais delas devem ser mostradas funcionando em vez de apenas mencionadas.
2. Crie a pasta
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/video-new/scripts/new_video.py" <product_dir> <video> \
--format <format> [--title "<title>"] [--duration <s>]
Isso copia _template/video, preenche o frontmatter do BRIEF (título, vídeo, formato, duração, idioma e revisor de product.yaml, versão 1) e deixa ambas as assinaturas vazias. Recusa um id duplicado.
3. Escreva os três documentos
Leia references/sheets.md para o formato de cada documento e exemplos preenchidos antes de escrever.
- BRIEF.md: intenção (cite as próprias palavras do usuário), público, os capítulos propostos, notas com todos os nomes e números fictícios que o vídeo usará (do elenco do produto, nunca novos sem perguntar) e uma entrada de changelog vazia para v1.
- COVERAGE.md: uma linha por funcionalidade com "deve explicar na tela? sim/não", o capítulo que a explica e a prova (o que o espectador vê acontecer). Uma funcionalidade que só é nomeada na tela final não é coberta: essa é exatamente a lacuna que custou mais versões. Inclua as partes configuráveis (configurações, acionadores incluindo os agendados, transferência, acompanhamentos) porque essas eram as funcionalidades que os revisores continuavam pedindo depois.
- CLAIMS.md: a linha de posicionamento (de
product.yaml, nunca de um documento de marketing), as frases a evitar (never_saymais qualquer coisa que o usuário adicionar), toda alegação que a narração deseja fazer e que precisa de aprovação, taglines aprovadas e os nomes canônicos do produto contra suas strings legadas.
Verifique cada alegação e funcionalidade em relação ao que você pode ver em sources/ e na documentação. Se o produto não fizer algo que o usuário pediu, diga com uma pergunta fechada e uma opção recomendada ("mostrar apenas o que existe" geralmente é o padrão correto). Não inclua uma funcionalidade na matriz que o código não possa sustentar.
4. Proponha os capítulos
Adicione a tabela de capítulos ao BRIEF.md. Uma ideia por capítulo, um enquadramento por capítulo, toda funcionalidade "deve explicar" mapeada para um capítulo. Abra com contexto (o nome do produto e uma linha sobre o que ele é), nunca no meio da UI. Enquadre toda a página em 1x por padrão; zooms profundos foram rejeitados duas vezes na produção original. Termine com amplitude (o que mais o produto faz), depois o lockup.
5. Pare e peça as assinaturas
Mostre ao usuário, em uma mensagem:
- A matriz de cobertura (as linhas "sim") e a tabela de capítulos.
- A linha de posicionamento, as alegações que precisam de aprovação e a tagline proposta.
- No máximo três decisões fechadas, cada uma com um padrão (por exemplo, a tagline, um nome de elenco, deixar uma funcionalidade de fora). Diga o que o silêncio significa: o padrão.
Em seguida, peça ao revisor para assinar. Ou eles escrevem seus nomes em coverage_signed_by e claims_signed_by no BRIEF.md, ou eles dizem com suas próprias palavras para você assinar em nome deles, e você executa:
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/video-new/scripts/sign.py" <video_dir> \
--coverage "<nome do revisor>" --claims "<nome do revisor>"
Nunca assine por iniciativa própria, nunca assine porque os documentos "parecem completos" e nunca assine com um nome que o revisor não forneceu. A assinatura é a declaração do revisor de que a matriz é o que eles usarão para julgar o vídeo. sign.py recusa uma matriz vazia ou uma linha de posicionamento ausente; sem flags, mostra apenas o status.
Não construa, renderize, grave narração ou despache subagentes aqui, mesmo que o usuário assine na mesma mensagem. Construir é /video-build, digitado pelo usuário. Essa separação é o que impede o agente de iniciar uma construção cara com um resumo não aprovado.
Relatório
| Item | Valor |
|---|---|
| Vídeo | videos/<video>/, formato, duração alvo |
| Cobertura | N funcionalidades para explicar na tela, M listadas apenas, capítulos |
| Alegações | posicionamento, alegações aguardando aprovação |
| Decisões | as até três perguntas fechadas e seus padrões |
| Assinaturas | não assinado (ou assinado por quem) |
Próximo passo, após assinado: /video-build <video>.