mohamed-stifi/repo-walkthrough-video

Vídeo de walkthrough do repositório

O objetivo é que um colega de equipe possa assistir ao vídeo e entender o repositório: para que serve, como as partes se encaixam e cada função executada de verdade, incluindo o que está quebrado hoje. Duas tarefas estão misturadas aqui e devem acontecer nesta ordem:

1. Testar o repositório de verdade. Todo comando mostrado no vídeo foi realmente executado e sua saída foi lida.
2. Gravar como uma história. Os capítulos seguem a forma do sistema, e cada um é narrado.

Um vídeo que mostra apenas comandos bem-sucedidos engana a equipe. As falhas que você encontrar durante os testes geralmente são a parte mais valiosa do vídeo, então dê a elas seu próprio capítulo de encerramento.

Estrutura de saída

Trabalhe em uma pasta fora do repositório. O usuário a escolhe; se não escolher, use uma pasta vizinha como <pai-do-repositorio>/video/, porque um caminho raiz como /video geralmente é somente leitura no macOS.

video/
├── <nome>-walkthrough.mp4    # vídeo completo: capítulos + faixa de legendas mov_text
├── <nome>-walkthrough.srt    # mesma narração, também utilizável como transcrição
├── chapters/NN-slug.mp4      # um arquivo por capítulo
├── README.md                 # índice de capítulos com horários de início, como regravar
├── src/                      # engine.py, make_readme.py, script.py (+ auxiliares)
├── work/                     # clone(s) descartável(is) do repositório: todos os comandos são executados aqui
└── build/                    # arquivos intermediários (voz por segmento, quadros, clipes)

Nunca execute os comandos de demonstração na cópia de trabalho do usuário. Clone-o em work/ (git clone <repo> work/<nome>) para que o vídeo possa quebrar coisas de propósito (manifestos ruins, falhas injetadas) e redefinir com git checkout . && git clean -fd. Se o checkout do usuário tiver alterações não confirmadas, mencione-as e deixe-as em paz.

Passo 1: Verificar as ferramentas e informar ao usuário o que está faltando

which vhs ffmpeg ffprobe jq; python3 -c "import PIL; print(PIL.__version__)"; say -v '?' | head -3

Se algo estiver faltando, diga ao usuário o que instalar e por que, antes de instalar (brew install vhs ffmpeg jq). Para o Pillow, não mexa no Python do sistema. Execute o mecanismo via uv: uv run --no-project --with pillow python engine.py .... Empacote em uma função de shell (py() { uv run --no-project --with pillow python "$@"; }), porque uma variável contendo o comando não se expandirá como uma unidade. O mesmo vale para qualquer coisa que o repositório precise, como Docker em execução, uma pilha de simulador ou credenciais. Peça-as ao usuário e nunca invente um segredo. Uma voz premium (Ajustes do Sistema → Acessibilidade → Conteúdo Falado, por exemplo "Ava (Premium)") soa muito melhor que a Samantha padrão. Ofereça-a, mas não bloqueie nela; VOICE=... engine.py --force regrava a voz depois.

Passo 2: Entender e testar o repositório antes de escrever uma palavra de narração

Leia o README, a documentação ou ADRs, os pontos de entrada da CLI (--help de cada subcomando), os marcadores de teste, o Makefile e a configuração de CI. Monte um inventário de cada função que um usuário pode exercitar: cada subcomando da CLI, cada suíte de teste, cada integração, cada modo de falha contra o qual o código se defende.

Depois execute tudo em work/ e anote:

• os comandos exatos que mostram bem cada recurso, com saída curta (canalize por jq, head, tail, cut -c1-160)
• o que falha e se é um bug real ou apenas seu ambiente (caminho padrão errado, variável de ambiente ausente). Corrija problemas de ambiente no clone ou com variáveis de ambiente e torne essa correção visível no vídeo, porque a equipe também enfrentará isso.
• como quebrar cada regra de segurança de propósito (um fixture, um sed em uma cópia), para que o vídeo possa mostrar a regra sendo acionada

Essas anotações se tornam o capítulo de descobertas. Mantenha-as como uma lista numerada de itens concretos.

Passo 3: Planejar os capítulos

Siga o pipeline do próprio sistema, não a listagem de pastas. Uma estrutura que funcionou bem:

#	Capítulo	Conteúdo
00	Boas-vindas	cartão de título, depois um slide "o que você verá"
01	Visão geral	um propósito em uma frase, o pipeline como caixas e setas, uma cena de terminal com a estrutura do repositório
02	Configuração	instalação, a CLI agrupada por propósito, a suíte de testes rápida
…	um capítulo por estágio do pipeline	comandos reais, mais uma cena "quebre de propósito" por regra
…	ao vivo / integração	os serviços reais de apoio, ponta a ponta
N-1	Contratos / hand-off	do que outras equipes dependem
N	Descobertas e próximos passos	a lista numerada de descobertas, depois o que fazer a seguir

Aponte para 1–3 minutos por capítulo e 15–25 minutos no total. Um capítulo é uma ideia; um segmento é uma tela mais uma narração. Mostre este esboço ao usuário (títulos dos capítulos e uma linha cada) antes de gravar.

Passo 4: Escrever src/script.py

Copie os scripts incluídos para a pasta de vídeo:

mkdir -p video/src && cp <dir-do-skill>/scripts/{engine.py,make_readme.py,agent.jq} video/src/
cp <dir-do-skill>/scripts/script_template.py video/src/script.py

script.py contém todas as palavras e todos os comandos. engine.py os transforma em vídeo. Leia references/script-format.md para o esquema completo de segmento, os layouts de slides e o estilo de narração. scripts/script_template.py mostra cada tipo de segmento com um exemplo funcional; construa o resto dos capítulos no mesmo formato (o Passo 3 fornece o esboço dos capítulos).

Regras de narração mais importantes:

• Escreva para o ouvido: frases curtas, sem markdown e soletre siglas que a voz pronuncia errado ("M C P", "C L I") ou adicione-as a SPOKEN em script.py.
• Diga o que o espectador deve olhar ("Olhe para as skills: zero"). A voz e a imagem devem concordar; então, se você alterar a saída de um comando (uma contagem, um fator de velocidade), corrija a frase também.
• As legendas (a barra inferior de uma cena de terminal) são uma linha que declara o ponto, com código entre crases.

Passo 5: Simular e depois gravar

cd video/src                          # `py` = Python com Pillow (veja Passo 1)
py engine.py --dry                    # executa todo comando de terminal em bash simples e imprime a saída, sem vídeo
py engine.py --dry --only 04          # um capítulo
py engine.py --only 04                # grava um capítulo (feedback rápido sobre a aparência)
py engine.py                          # tudo que está faltando ou mudou, depois monta o vídeo completo
py engine.py --only 07 --reuse-terms  # mantém os clipes VHS, refaz apenas a voz e os quadros (correções de narração)
py make_readme.py                     # escreve README.md com o índice de capítulos

Sempre simule primeiro. Leva minutos em vez de uma hora e captura todo comando que dá erro, trava ou imprime demais. Grave um capítulo primeiro e veja os quadros antes da construção completa:

ffmpeg -v error -ss 20 -i chapters/04-*.mp4 -frames:v 1 build/check.png   # depois leia o PNG

Uma construção completa leva muito tempo (cerca de 40 minutos para 21 minutos de vídeo). Execute-a em segundo plano e aguarde o aviso de conclusão em vez de ficar verificando. Os capítulos são armazenados em cache por um hash de seu script, então reexecutar reconstrói apenas o que mudou.

Passo 6: Verificar e entregar

ffprobe -v error -show_chapters -show_streams -of compact video/<nome>-walkthrough.mp4 | head -40

Verifique o seguinte:

• a duração
• 1920×1080 h264, aac e uma faixa de legendas mov_text
• um marcador de capítulo por capítulo
• quadros de amostra de alguns capítulos: nenhum texto transbordando das caixas, legendas dentro de duas linhas

Depois informe ao usuário os caminhos exatos do MP4, da pasta chapters/, do SRT e do README. Adicione como abrir (open video/<nome>-walkthrough.mp4; QuickTime ou VLC mostram os menus de capítulo e legendas) e a lista de descobertas. Mencione quaisquer contêineres ou serviços que você deixou em execução e como pará-los.

Armadilhas já resolvidas (mantenha-as em mente ao editar o mecanismo)

• Shells em sandbox: vhs, Docker, caches do uv e say frequentemente falham sob um sandbox de comando ("Operação não permitida", erros de socket Docker). Esses comandos precisam ser executados fora dele. open também é bloqueado, então forneça ao usuário o comando para executar sozinho.
• Queda de quadros no VHS: o padrão de 50 fps deixa cair quadros em cenas longas. O mecanismo usa Set Framerate 15.
• Output do VHS deve ser um nome de arquivo simples. Execute vhs com cwd definido para a pasta de saída.
• Strings do VHS não têm escapes. Aspas do json.dumps quebram sequências de escape do PS1. Use q() no mecanismo, que escolhe um delimitador ", ' ou ` que o texto não contenha.
• Wait trava se o padrão não corresponder ao prompt. O mecanismo define um PS1 que termina em $ e usa WaitPattern /[>$]$/. Comandos que imprimem uma linha final terminando em $ ou > podem encerrar uma espera precocemente, então adicione uma pause lá.
• Cenas longas (um agente de IA, uma execução de pipeline): defina "speedup": True no segmento. O mecanismo acelera o clipe para aproximadamente a duração da narração e carimba acelerado ×N.N no cabeçalho, então mencione que está acelerado.
• Transbordamento de texto em slides: wrap() mede spans de código na fonte monoespaçada. Mantenha os corpos das caixas curtos e divida caminhos longos em duas linhas.
• Loops de espera: um loop pgrep -f <padrão> corresponde a si mesmo. Espere por um PID ou um arquivo.
• Hooks anteriores ("before": [...] em um capítulo) preparam o estado: redefine um contêiner de banco de dados, aciona um pipeline, injeta uma falha. Coloque o desfazer (redefinir, desinjetar) no mesmo capítulo, para que uma reconstrução de um capítulo nunca deixe a plataforma quebrada.
• Segredos necessários para a demonstração vão em um arquivo ignorado pelo git no clone (por exemplo dev-vault.env). Nunca mostre seus valores na tela e nunca os envie.

Mostrando um agente de IA em ação (opcional)

Se o repositório constrói ou configura um agente, a cena mais forte é o agente diagnosticando uma falha real e injetada. Execute-o sem cabeça com saída stream-json e formate o stream com o agent.jq incluído (uma linha por chamada de ferramenta, depois a resposta):

claude -p "<pergunta>" --output-format stream-json --verbose | jq -rj -f /caminho/para/video/src/agent.jq

Marque esse segmento com "speedup": True e redefina a falha depois no mesmo capítulo.