carnufex/pr-demo

Demonstração de PR (PR demo)

Um revisor deve entender uma alteração em bem menos de um minuto sem abrir o diff: o que mudou, como funciona agora, a prova de que funciona e onde olhar. Os fatos do repositório — idioma das legendas, como gravar o fluxo alterado, onde publicar — estão em .claude/profiles/delivery.md (Demo, Notify).

Curto e direto vence completo. Cinco cenas em 30 segundos, nesta ordem, e omita o que a alteração não tem em vez de encher linguiça:

1. O que mudou — o título e no máximo três bullets.
2. Como funciona agora — o fluxo, com o nó alterado marcado.
3. Antes e depois — apenas para algo visível; pule para uma alteração de backend.
4. A correção em execução — a gravação, cortada na parte que importa, com menos de 12 s.
5. Prova — as verificações da chave de revisão e os testes em uma única cena key. Eles respondem à mesma pergunta, portanto não ganham uma cena cada.

1. Coletar o material

Em out/demo/<pr ou issue>/ (ignorado pelo git):

• As evidências da chave de revisão: out/review-key/<n>/result.json e o veredito do key-reviewer (review-key).
• Capturas de tela para uma alteração visível ao usuário: a mesma visão antes (branch base) e depois, mesmo tamanho e dados. Corte na parte que mudou; uma página inteira a 1280 px torna a mudança pequena demais para ver.
• Uma gravação do fluxo alterado (o comando Demo do perfil, ou Playwright com browser.newContext({ recordVideo: { dir, size: { width: 1280, height: 800 } }, viewport: { width: 1280, height: 800 } }) em torno das etapas da verificação e2e que o cobre; o arquivo aparece quando o contexto fecha). Mantenha abaixo de 20 s: comece na tela que importa, sem logins na câmera.
• O fluxo da alteração como um flowchart LR (ou TD) do Mermaid: cinco a nove nós, o caminho do usuário ou da requisição, com :::changed no que mudou, :::added no que é novo e :::removed no que foi removido. Explique comportamento, não arquivos.
• Testes que foram executados, com um número cada (476 testes, 12 fluxos).

2. Escrever demo.json

Ao lado do material (caminhos relativos a ele). Texto no idioma de legenda do perfil; curto — uma cena é lida em seus segundos. Crases e **negrito** funcionam.

{
  "lang": "pt",
  "brand": "**loja** · PR #352",
  "ref": "Fecha #331",
  "kicker": "Correção de bug",
  "title": "O checkout cabe em 1280 px",
  "subtitle": "O botão de pagamento cobria o carrinho e o campo de cupom tinha 49 px de largura.",
  "chips": [{ "text": "Chave de revisão: APROVADO", "ok": true }, "3 arquivos"],
  "scenes": [
    { "type": "title", "seconds": 3 },
    { "type": "bullets", "items": ["…", "…", "…"], "seconds": 5 },
    { "type": "flow", "mermaid": "flowchart LR\n  A[Largura] --> B{\"< 1440 px?\"}\n  B -- sim --> C[Ícones]:::changed", "seconds": 6 },
    { "type": "compare", "before": "antes.png", "after": "depois.png", "seconds": 5 },
    { "type": "clip", "heading": "Gravado em 1280 px", "src": "execucao.webm", "caption": "e2e: checkout-ajuste", "speed": 1.5, "maxSeconds": 12 },
    { "type": "key", "result": "../../review-key/331/result.json", "baseFails": true, "seconds": 7,
      "rows": [{ "ok": true, "text": "`verificar.sh` · 476 testes" }] },
    { "type": "end", "title": "Pronto para revisão", "lines": ["PR: **github.com/…/pull/352**", "3 da manhã: …"], "seconds": 3 }
  ]
}

Cenas: title, bullets (items, no máximo quatro), flow (mermaid, legend: false para ocultar a legenda), compare (before, after, rótulos; layout: "stack" coloca uma sobre a outra, para faixas largas como uma barra de ferramentas), clip (src .webm/.mp4, from/to segundos, speed, maxSeconds padrão 20, crop {x, y, w, h} nos pixels da gravação para ampliar a parte que importa; sua duração vem do arquivo), key (result = result.json da verificação da chave ou um objeto; verdict, baseFails, claim, rows e count {value, total, label} substituem — por exemplo, uma verificação que executa oito casos fica melhor como 8/8), checks (items com name, detail, ok), end (title, lines). Toda cena aceita heading, kicker e seconds. Omita o que a alteração não tem — uma alteração de backend não tem compare ou clip; uma refatoração pura tem uma cena key com paridade e pouco mais.

O painel esquerdo da cena key comporta até oito linhas e recebe rows próprias antes das verificações da chave, então os testes vão para lá como uma linha cada ("verificar.sh · 476 testes") em vez de em uma cena checks depois. Use uma cena checks separada apenas quando não houver chave de revisão para mostrar.

Redação

As legendas são lidas nos segundos em que estão na tela, então cada palavra tem que valer. Três regras, aprendidas com demonstrações que irritavam o leitor:

• Informe o resultado, não o elogie. O carimbo do veredito e "verificado independentemente pelo key-reviewer" já dizem que a chave passou e quem verificou. Adicionar "APROVADO, sem trapaça" ou "totalmente verificado" soa como o autor corrigindo o próprio dever de casa. Nunca editorialize sobre o veredito.
• Rótulos de contagem são substantivos simples: verificações passam, casos idênticos, testes. Um verbo como falha/falhador como rótulo transforma "5/5" em uma frase que se lê ao contrário — "5 de 5 falham" parece que a alteração está quebrada quando significa que a branch base está. Se precisar dizer que a base falha, isso é a linha baseFails, que se expressa sozinha.
• Sem enchimento. Corte "com sucesso", "conforme esperado", "isso garante que" e qualquer bullet que repita o título. Se um bullet fizesse um revisor dizer "sim, obviamente", não é um bullet.

3. Renderizar

node <diretório deste skill>/scripts/render-demo.mjs out/demo/<n>/demo.json [--webm]

Isso desenha cada cena no Chromium quadro a quadro (texto nítido, sem quadros perdidos) e codifica demo.mp4 (H.264, reproduzido inline no Slack, GitHub e navegadores), demo.png (um pôster: a cena do fluxo ou da chave) e, com --webm, um demo.webm em VP9. Precisa do ffmpeg e usa o Playwright do projeto, caso contrário o instala uma vez em ~/.cache/carnufex-showcase. Cerca de um segundo de renderização por segundo de vídeo.

Assista antes de enviar: extraia quadros de cada cena (ffmpeg -ss <t> -i demo.mp4 -frames:v 1 f.png) e olhe para eles. Texto cortado, diagrama vazio, clipe de tela de login: corrija e renderize novamente.

4. Publicar

No canal que o Notify do perfil nomeia, como o bot, para que a pessoa receba uma notificação real (uma mensagem postada através de um conector Slack vem da própria pessoa, e o Slack não notifica ninguém de suas próprias mensagens). Uma thread por PR: a demonstração inicia a thread do PR; tudo depois dela — CI, rodadas de revisão, merge, deploy, verificação ao vivo, rollback — é uma resposta nessa thread (ship publica essas). O canal fica uma linha por PR, entre todos os repositórios. Escreva a mensagem em um arquivo; ela deve ser autossuficiente (Slack mrkdwn) e começar com o repositório:

*<repo>* · PR #<n> · <título> — pronto para revisão
<URL do PR>
• <o que mudou, linha 1>
• <linha 2>
Chave de revisão (<tipo>): *APROVADA*, verificada independentemente: <uma linha do veredito>
3 da manhã: <sinal>

node <diretório deste skill>/scripts/post-slack.mjs --channel <id> --pr <URL do PR> --file out/demo/<n>/demo.mp4 --title "<repo> PR #<n>: <título> (<s> s)" --comment-file out/demo/<n>/message.md
node <diretório deste skill>/scripts/post-slack.mjs --channel <id> --pr <URL do PR> --text-file update.md [--broadcast]

--pr encontra a thread do PR pela URL no canal (nenhum estado mantido): encontrada, a postagem vai para a thread; não encontrada, a inicia. --text-file posta uma mensagem sem arquivo; --broadcast também mostra uma resposta de thread no canal (use para o resultado: ao vivo, ou revertido). Ele imprime a thread e o link permanente. O token do bot vem de SLACK_BOT_TOKEN ou do plugin slack-channel em ~/.claude/channels/slack/.env; o bot deve estar no canal (not_in_channel: /invite @<bot>). Sem bot, volte para o conector Slack (slack_get_file_upload_url → POST os bytes → slack_complete_file_upload) e avise que nenhuma notificação será enviada.

Coloque as mesmas três linhas, o fluxograma Mermaid e o link do Slack na descrição do PR (o GitHub renderiza Mermaid; ele não reproduz um vídeo enviado através da API).