HomenShum/NodeKit

NodeKit Present

Convierte artefactos de desarrollo verificados en una presentación viva. Trata el deck como una proyección del registro de cambios, nunca como una fuente independiente de afirmaciones.

Lee el contrato de historia de cambio antes de crear o actualizar artefactos de presentación.

Flujo de trabajo

1. Clasifica el nivel del cambio. Omite los decks para trabajo trivial; usa una tarjeta de cambio para una corrección menor, un mini-deck de 3 a 5 diapositivas para una característica importante, y un deck completo con apéndice para lanzamientos o hackathons.
2. Crea o actualiza changes/<change-id>/change.yaml. Registra la audiencia, el problema, el estado anterior, la decisión, las alternativas, los sistemas afectados, el flujo de trabajo del usuario, los requisitos de prueba, las limitaciones y el nivel de presentación.
3. Captura evidencia mientras se realiza el trabajo: capturas de pantalla de referencia y posteriores, commits exactos, identidad del despliegue, pruebas, benchmarks, trazas, artefactos, exportaciones y fallos conocidos. Conserva los recibos originales.
4. Construye un índice de evidencia. Asigna a cada afirmación material un estado e identificadores de evidencia. Etiqueta claramente las afirmaciones planificadas, inferidas, afirmadas por el usuario y medidas.
5. Planifica cada diapositiva antes de renderizar. Indica su propósito, pregunta de la audiencia, conclusión, función narrativa, elemento visual dominante, identificadores de evidencia, presupuesto de densidad y objetivo de las notas del orador.
6. Utiliza el transporte NodeSlide instalado en este orden: adaptador nativo del repositorio, CLI NodeSlide, MCP NodeSlide o API del paquete. Inspecciona las capacidades primero y nunca asumas que las escrituras alojadas, la exportación o la aprobación están disponibles.
7. Propón cambios al deck contra la versión fijada del mismo. Valida, compara y aplica a través de la política del host; no evites la gobernanza de NodeSlide por conveniencia.
8. Verifica cada afirmación material contra el commit o despliegue actual. Actualiza las capturas de pantalla y métricas obsoletas. Mantén visibles las limitaciones.
9. Exporta el formato editable solicitado y vuelve a abrirlo. Verifica el deck renderizado, las notas del orador, los enlaces a las fuentes y cualquier viaje de ida y vuelta PPTX.
10. Deriva el guion de la demo, la sección README, las notas de la versión y el texto de la entrega a partir de la misma Historia de Cambio e Índice de Evidencia.

Un clip de demo es un recorrido renderizado, nunca una grabación de pantalla

Esta sección existe debido a un fallo medido. Un despliegue de producción fue verificado 11/11 con un clip grabado, y el clip era una captura sin procesar de Playwright: sin encuadre de enfoque, sin subtítulos, sin streaming visible ni llamadas a herramientas, sin diapositivas. Las herramientas para cada una de esas cosas ya existían y esta habilidad no nombraba ninguna, por lo que se improvisó mal en lugar de ejecutarse bien.

FeatureClipStudio (feature-walkthrough-gif/) es el pipeline de captura a renderizado, y cubre las cuatro cosas que una captura sin procesar nunca tiene:

lo que le falta a una captura sin procesar	lo que hace el pipeline
enfoque en lo que importa	cámara con zoom al enfoque, cursor animado que se desliza a cada clic con una ondulación
explicación	subtítulos de paso por estado
visibilidad del trabajo	carga y streaming capturados EN VIVO: spinner girando, resultados llegando
los detalles internos cuando la afirmación depende de ellos	paneles de evidencia JSON/estado sin procesar

npm run capture   # Playwright impulsa el flujo en vivo y graba cada estado de la interfaz
npm run studio    # storyboard de los estados capturados
npm run render    # Remotion renderiza el recorrido
npm run judge     # Gemini observa el RENDER y lo puntúa

judge-video.mjs es la puerta de entrada, y es el que se debe ejecutar antes de considerar un clip terminado. Observa el MP4 renderizado contra una rúbrica de anti-hero-shot y devuelve defectos con marca de tiempo en P0/P1/P2 — P0 bloquea la publicación. Su propio encabezado indica el punto: el corte final deja de ser la única etapa que los ojos humanos revisan. Juzga el MP4 en lugar del GIF; GIF no es un MIME de video compatible.

No entres en un bucle de pulido de re-renderizado por P2 que el juez ya haya aprobado.

Dos ejes, y el segundo es el que falla

judge-video.mjs puntúa CRAFT — verdad del cursor, ritmo, legibilidad, movimiento — y por separado puntúa COMPREHENSION, las diez cosas que un espectador debe entender realmente:

persona · propósito · caso_de_uso · claridad_de_función · interacción_completa
capacidad_de_respuesta · flujo · resultado · sentido_para_no_expertos · transferencia

Son ortogonales, y un corte puede estar bien hecho y ser incomprensible. Medido en un render real: craft pasó con un veredicto de publicar, y comprensión obtuvo 1 en los diez — nada ausente, nada explícito, todo meramente implícito — con el juez nombrando 0:06 como el segundo en que un no experto se perdió ("conceptos de arquitectura en capas y registros de terminal").

sentido_para_no_expertos es la prueba de la mamá y BLOQUEA por sí mismo, independientemente de los totales. Una puerta que aprueba un video que su propio juez dice que nadie fuera del campo podría seguir no es una puerta. Las puntuaciones uniformes en los diez se marcan en lugar de promediarse, porque "todos 1" significa todo implícito y nada explícito, lo cual es un hallazgo y no una aprobación mediocre.

EL BUCLE ES EL VALOR POR DEFECTO, no una verificación final: renderiza, juzga, lee lo que dice que falta, vuelve a cortar, vuelve a juzgar. Tres cortes en una película la movieron de 10/20 a 13/20 y, más útilmente, le dijeron al creador que la historia se había construido en torno al momento equivocado — algo que ninguna cantidad de autorevisión había sacado a la luz. Detente cuando la comprensión esté clara y los defectos restantes sean P2.

NodeSlide para el deck, NodeVideo para la evidencia a nivel de fotograma — un fotograma presentado como el producto en ejecución debe vincularse al despliegue del que provino, y presentedAs es lo que hace que eso sea verificable.

De dónde provienen los videos de referencia

Mobbin funciona para la interfaz de usuario porque es un corpus que se OBSERVA y CITA, nunca se copia. El video necesita la misma disciplina y se divide en dos tipos, que no son intercambiables:

Referencias de FLUJO: lo que un producto real realmente hace, paso a paso. Page Flows es el análogo directo: recorridos de usuario grabados en lugar de capturas de pantalla, 20.000+ aplicaciones, organizadas por tarea — registro, actualización, cancelación — incluyendo el diálogo de consentimiento, la validación de campos, el estado vacío y la pantalla de éxito. Su propio encuadre es la regla anti-hero-shot declarada desde el otro lado: Mobbin te muestra el destino, Page Flows te muestra el viaje. ScreensDesign cubre la incorporación de usuarios y los muros de pago con señales de ingresos adjuntas. Úsalos para responder "¿qué estados contiene un flujo real de este tipo y cuáles me estoy saltando?"

Referencias de OFICIO: cómo se construye una película de lanzamiento. Comienza con YouTube. El juez lee una URL de YouTube directamente — verificado: Gemini observó una y describió sus segundos de apertura y duración solo con la URL, sin descarga. Por lo tanto, una referencia se CITA, nunca se copia, lo que disuelve por completo la cuestión de la licencia y convierte el localizador en una URL más una marca de tiempo:

El agente construye su propio corpus en lugar de esperar a que se le entregue uno. yt-dlp BUSCA en YouTube y lee metadatos; no se descarga nada, y Gemini observa la URL:

node find-references.mjs "Raycast product demo" "Linear product demo"   # buscar, triage, observar
node judge-video.mjs out/demo.mp4                                       # corpus usado automáticamente
node judge-video.mjs out/demo.mp4 --no-reference                        # optar por no participar

find-references.mjs hace triage ANTES de gastar tokens: cualquier cosa de más de 180 segundos es rechazada por defecto como la forma incorrecta y el costo incorrecto para un recorrido corto, con el motivo impreso. Medido en una ejecución real — una demo propia de 39 segundos costó 3,9k tokens de aviso, una de 18 minutos 102k. Luego escribe references/video/<id>.json: hechos atómicos con marca de tiempo (0:07 movimiento — las teclas se vuelven verdes al presionar), hookSeconds, estadosMostrados, quéRobar y quéNoRobar, más una lista noEjecutado para cualquier cosa que no pudo determinar. Hechos, nunca adjetivos — un hecho puntúa a un candidato, un adjetivo no puede.

El veredicto gana un bloque referencia — momentoÚnico, ritmoDeEstado, propósitoDelMovimiento, quéRobar y quéNoRobar — con una marca de tiempo requerida para cada afirmación sobre la referencia. Todas las películas de lanzamiento de productos que vale la pena estudiar ya están en YouTube y son la fuente principal; las bibliotecas seleccionadas a continuación son una capa de descubrimiento sobre ella, útiles para ENCONTRAR candidatos en lugar de para verlos.

El costo es real: una referencia de 18 minutos midió 102k tokens de aviso. Prefiere un corte de 30 a 90 segundos y pasa como máximo dos o tres referencias.

FlowJam es una biblioteca seleccionada a mano de videos de SaaS y lanzamiento de productos; la biblioteca de Tella y los análisis de Vidico publican ejemplos con el razonamiento adjunto. Úsalos para el ritmo, el momento único y dónde el movimiento está haciendo trabajo en lugar de decorar.

No pegues ninguno de los dos tipos en la rúbrica como prosa. Grábalos de la misma manera que se registra una observación de Mobbin: un hecho atómico, con un locatorDescription que para el video es una MARCA DE TIEMPO, citada a la URL de origen. La afirmación es "a los 0:12 el estado de carga se mantiene durante 1,4 segundos antes del resultado", no "su ritmo es bueno". Una regla derivada de una observación con marca de tiempo se puede puntuar; un adjetivo no.

Licencia: observa y atribuye, nunca re-alojes. licenceMode en el esquema de observación es un valor único enumerado a propósito — extenderlo a una nueva clase de fuente es una revisión de licencia y una edición deliberada del esquema, no una cadena escrita.

Una película de lanzamiento se dirige, luego se renderiza — el contrato de video de lanzamiento

Todo lo anterior juzga un corte que ya existe. Una película de LANZAMIENTO falla antes que eso: se construye en torno al momento equivocado, o se entrega después del lanzamiento, y ningún bucle de juez puede recuperar ninguna de las dos cosas. Estudiado en vivo en Motion Studio (películas de lanzamiento para startups de nivel YC): su proceso es Dirección → Primer borrador → Revisiones → Entrega, y "un director humano toma todas las decisiones de gusto". Ese orden es el producto. nodekit launch-video lo lleva como un contrato rechazable, por lo que un agente de codificación impulsado recorre las etapas en lugar de saltar a npm run render:

nodekit launch-video declare --application <slug> --out launch-video.json
# 1 BRIEF      completar producto, historia (palabras del interesado), audiencia, fechaDeLanzamiento, canales
# 2 DIRECCIÓN  momentoÚnico, compases ordenados, referencias a través de find-references.mjs (hechos
#              con marca de tiempo, nunca adjetivos), duraciónObjetivoSegundos ≤ 180 — luego un HUMANO aprueba
# 3 BORRADORES capturar → estudio → renderizar (FeatureClipStudio o NodeVideo), judge-video.mjs en
#              el MP4, registrar el ciclo: corte, puntuaciones del juez, notasHumanas, disposición
# 4 ENTREGA   corteFinal + reciboDelJuez + aprobación humana, entregadoEn ANTES de fechaDeLanzamiento
nodekit launch-video check --contract launch-video.json   # rechaza en cada salida de etapa

Lo que el control rechaza, y por qué existe cada rechazo:

• borradores antes de una dirección aprobada — el primer corte se alinea con una dirección, no la descubre; un render hecho antes de que regrese la dirección es la factura de revisión.
• una afirmación de referencia sin una marca de tiempo — "su ritmo es bueno" no se puede puntuar; "a los 0:12 el estado de carga se mantiene 1,4 segundos" sí.
• un ciclo final que falla sentido_para_no_expertos — la prueba de la mamá bloquea la entrega por sí sola, la misma regla que el bucle del juez anterior; el contrato lo convierte en una salida de etapa en lugar de un consejo.
• entregadoEn después de fechaDeLanzamiento — una película de lanzamiento entregada después del lanzamiento es una retrospectiva.
• entrega sin una aprobación humana — el juez es consultivo; la decisión de gusto es una persona.

El bucle del juez sigue siendo el bucle interno de la etapa 3 exactamente como se describe anteriormente. El contrato agrega lo que el bucle solo nunca retuvo: las etapas en orden, el humano en las dos puertas de gusto y la fecha.

Carril paralelo

Para una implementación grande, ejecuta el trabajo de presentación como un carril de solo lectura junto a la construcción y el control de calidad. Redacta el problema y la arquitectura temprano; reemplaza los marcadores de posición solo con evidencia verificada de etapas posteriores. Bloquea el lanzamiento solo por afirmaciones no respaldadas, pruebas requeridas faltantes, evidencia obsoleta o una exportación rota.

Lenguaje de finalización

• Di redactado cuando existan planes de diapositivas.
• Di vinculado-a-evidencia cuando cada afirmación material se resuelva con evidencia actual.
• Di exportación-verificada solo después de que el archivo de salida solicitado se vuelva a abrir correctamente.
• Di listo-para-lanzamiento solo cuando tanto la prueba de la aplicación como la prueba de la presentación pasen.

No conviertas una prueba unitaria verde en una afirmación de producción, un HTTP 200 en una prueba de navegador, o un juicio de modelo consultivo en un veredicto autoritativo.