carnufex/pr-demo

PR demo

Un revisor debería entender un cambio en menos de un minuto sin abrir el diff: qué cambió, cómo funciona ahora, prueba de que funciona y dónde mirar. Los hechos del repositorio (idioma de los subtítulos, cómo grabar el flujo cambiado, dónde publicar) están en .claude/profiles/delivery.md (Demo, Notify).

Corto y directo es mejor que completo. Cinco escenas en 30 segundos, en este orden, y omite lo que el cambio no tiene en lugar de rellenarlo:

1. Qué cambió — el título y como máximo tres viñetas.
2. Cómo funciona ahora — el flujo, con el nodo cambiado marcado.
3. Antes y después — solo para algo que se pueda ver; omítelo para un cambio de backend.
4. La corrección en ejecución — la grabación, recortada a la parte que importa, menos de 12 s.
5. Prueba — las comprobaciones de la clave de revisión y las pruebas en una sola escena key. Responden a la misma pregunta, así que no obtienen una escena cada una.

1. Recopila el material

En out/demo/<pr o issue>/ (ignorado por git):

• La evidencia de la clave de revisión: out/review-key/<n>/result.json y el veredicto de key-reviewer (review-key).
• Capturas de pantalla para un cambio visible por el usuario: la misma vista antes (la rama base) y después, mismo tamaño y datos. Recorta a la parte que cambió; una página completa a 1280 px hace que el cambio sea demasiado pequeño para verlo.
• Una grabación del flujo cambiado (el comando Demo del perfil, o Playwright con browser.newContext({ recordVideo: { dir, size: { width: 1280, height: 800 } }, viewport: { width: 1280, height: 800 } }) alrededor de los pasos de la comprobación e2e que lo cubre; el archivo aparece cuando se cierra el contexto). Mantenla por debajo de 20 s: comienza en la pantalla que importa, sin inicios de sesión en cámara.
• El flujo del cambio como un flowchart LR (o TD) de Mermaid: cinco a nueve nodos, la ruta del usuario o de la solicitud, con :::changed en lo que cambió, :::added en lo que es nuevo y :::removed en lo que desapareció. Explica el comportamiento, no los archivos.
• Pruebas que se ejecutaron, con un número cada una (476 tests, 12 flows).

2. Escribe demo.json

Junto al material (las rutas son relativas a él). Texto en el idioma de los subtítulos del perfil; corto — una escena se lee en sus segundos. Las comillas invertidas y **negrita** funcionan.

{
  "lang": "en",
  "brand": "**tienda** · PR #352",
  "ref": "Cierra #331",
  "kicker": "Corrección de error",
  "title": "El checkout cabe a 1280 px",
  "subtitle": "El botón de pago cubría el carrito y el campo de cupón tenía 49 px de ancho.",
  "chips": [{ "text": "Clave de revisión: APROBADO", "ok": true }, "3 archivos"],
  "scenes": [
    { "type": "title", "seconds": 3 },
    { "type": "bullets", "items": ["…", "…", "…"], "seconds": 5 },
    { "type": "flow", "mermaid": "flowchart LR\n  A[Ancho] --> B{"< 1440 px?"}\n  B -- sí --> C[Iconos]:::changed", "seconds": 6 },
    { "type": "compare", "before": "antes.png", "after": "despues.png", "seconds": 5 },
    { "type": "clip", "heading": "Grabado a 1280 px", "src": "run.webm", "caption": "e2e: checkout-fit", "speed": 1.5, "maxSeconds": 12 },
    { "type": "key", "result": "../../review-key/331/result.json", "baseFails": true, "seconds": 7,
      "rows": [{ "ok": true, "text": "`verify.sh` · 476 tests" }] },
    { "type": "end", "title": "Listo para revisión", "lines": ["PR: **github.com/…/pull/352**", "3 am: …"], "seconds": 3 }
  ]
}

Escenas: title, bullets (items, como máximo cuatro), flow (mermaid, legend: false para ocultar la leyenda), compare (before, after, etiquetas; layout: "stack" las pone una encima de la otra, para tiras anchas como una barra de herramientas), clip (src .webm/.mp4, from/to segundos, speed, maxSeconds por defecto 20, crop {x, y, w, h} en píxeles de la grabación para ampliar la parte que importa; su duración proviene del archivo), key (result = result.json de keycheck o un objeto; verdict, baseFails, claim, rows y count {value, total, label} anula — p. ej., una comprobación que ejecuta ocho casos se lee mejor como 8/8), checks (items con name, detail, ok), end (title, lines). Cada escena acepta heading, kicker y seconds. Omite lo que el cambio no tiene — un cambio de backend no tiene compare o clip; una refactorización pura tiene una escena key con paridad y poco más.

El panel izquierdo de la escena key contiene hasta ocho filas y acepta rows propias antes de las comprobaciones de la clave, por lo que las pruebas van allí como una fila cada una ("verify.sh · 476 tests") en lugar de en una escena checks después. Usa una escena checks separada solo cuando no haya una clave de revisión que mostrar.

Redacción

Los subtítulos se leen en los segundos que están en pantalla, por lo que cada palabra debe aportar. Tres reglas, aprendidas de demos que molestaban a su lector:

• Indica el resultado, no lo elogies. El sello de veredicto y "verificado independientemente por key-reviewer" ya dicen que la clave pasó y quién la verificó. Agregar "APROBADO, sin trampas" o "totalmente verificado" se lee como si el autor calificara su propio trabajo. Nunca editorialices sobre el veredicto.
• Las etiquetas de recuento son sustantivos simples: checks pass, cases identical, tests. Un verbo como fail/falla como etiqueta convierte "5/5" en una oración que se lee al revés — "5 de 5 falla" suena como si el cambio estuviera roto cuando significa que la rama base lo está. Si necesitas decir que la base falla, esa es la fila baseFails, que se explica por sí misma.
• Sin relleno. Elimina "exitosamente", "como se esperaba", "esto asegura que" y cualquier viñeta que repita el título. Si una viñeta haría que un revisor dijera "sí, obviamente", no es una viñeta.

3. Renderizar

node <directorio de este skill>/scripts/render-demo.mjs out/demo/<n>/demo.json [--webm]

Dibuja cada escena en Chromium fotograma a fotograma (texto nítido, sin fotogramas perdidos) y codifica demo.mp4 (H.264, se reproduce directamente en Slack, GitHub y navegadores), demo.png (un póster: la escena de flujo o clave) y, con --webm, un VP9 demo.webm. Necesita ffmpeg y toma Playwright del proyecto, de lo contrario lo instala una vez en ~/.cache/carnufex-showcase. Alrededor de un segundo de renderizado por segundo de video.

Míralo antes de enviarlo: extrae fotogramas de cada escena (ffmpeg -ss <t> -i demo.mp4 -frames:v 1 f.png) y míralos. Texto cortado, un diagrama vacío, un clip de una pantalla de inicio de sesión: corrige y renderiza de nuevo.

4. Publicar

En el canal que nombra la sección Notify del perfil, como el bot, para que la persona reciba una notificación real (un mensaje publicado a través de un conector de Slack proviene de la persona misma, y Slack no notifica a nadie de sus propios mensajes). Un hilo por PR: la demo inicia el hilo del PR; todo después — CI, rondas de revisión, fusión, despliegue, la comprobación en vivo, un retroceso — es una respuesta en ese hilo (ship publica esos). El canal se mantiene con una línea por PR, en todos los repositorios. Escribe el mensaje en un archivo; debe ser autónomo (mrkdwn de Slack) y comenzar con el repositorio:

*<repositorio>* · PR #<n> · <título> — listo para revisión
<URL del PR>
• <qué cambió, línea 1>
• <línea 2>
Clave de revisión (<tipo>): *APROBADO*, verificado independientemente: <una línea del veredicto>
3 am: <señal>

node <directorio de este skill>/scripts/post-slack.mjs --channel <id> --pr <URL del PR> --file out/demo/<n>/demo.mp4 --title "<repositorio> PR #<n>: <título> (<segundos> s)" --comment-file out/demo/<n>/mensaje.md
node <directorio de este skill>/scripts/post-slack.mjs --channel <id> --pr <URL del PR> --text-file actualizacion.md [--broadcast]

--pr encuentra el hilo del PR por su URL en el canal (no se guarda estado): encontrado, la publicación va al hilo; no encontrado, lo inicia. --text-file publica un mensaje sin archivo; --broadcast también muestra una respuesta de hilo en el canal (úsalo para el resultado: en vivo, o revertido). Imprime el hilo y el permalink. El token del bot proviene de SLACK_BOT_TOKEN o del plugin de canal de Slack en ~/.claude/channels/slack/.env; el bot debe estar en el canal (not_in_channel: /invite @<bot>). Sin un bot, recurre al conector de Slack (slack_get_file_upload_url → POST de los bytes → slack_complete_file_upload), e indica que no se enviará ninguna notificación.

Pon las mismas tres líneas, el diagrama de flujo Mermaid y el enlace de Slack en la descripción del PR (GitHub dibuja Mermaid; no reproduce un video subido a través de la API).