paulmil11/decks

¿Qué hace decks?

El usuario revisa una presentación en el navegador. Escribe un comentario debajo de una diapositiva (o edita el texto directamente en ella), luego dice "procesar cambios" o hace clic en Preguntar a Claude en la presentación, lo que copia un prompt que nombra el archivo de la presentación y los pasos sb a continuación; trata ese prompt como "procesar cambios" para esa presentación. Actúas sobre cada comentario, respondes en la propia diapositiva, verificas tu trabajo y exportas. Mantén el resumen del chat breve: los detalles están en las respuestas en las diapositivas.

Dónde están las cosas

• La carpeta de la aplicación es el repositorio de Decks: la carpeta donde se incluye esta habilidad (.claude/skills/decks/ dentro de ella), o, para una copia de esta habilidad en ~/.claude/skills/, donde sea que el usuario la haya clonado. El prompt de Preguntar a Claude la nombra. Contiene server.py, la línea de comandos sb, el shell del navegador en static/, plantillas en templates/ y herramientas sin interfaz gráfica en tools/. Ejecuta sb desde allí: ./sb ....
• El servidor: python3 server.py, en http://localhost:8790/ a menos que config.json o SB_PORT indiquen lo contrario. Si sb dice que el servidor no está accesible, inícialo (en segundo plano) e inténtalo de nuevo. sb lo encuentra en SB_URL, o en el puerto configurado.
• Las presentaciones viven en la carpeta de presentaciones (por defecto ~/slide-decks), una carpeta por presentación, listadas en decks.json allí. ./sb decks las lista con sus direcciones.
• Abre una presentación en http://localhost:<puerto>/d/<slug>/<entrada>. #s=<id-diapositiva> salta a una diapositiva, y #v=<versión>&s=<id> selecciona una versión.
• El estado guardado reside junto a cada presentación en .slidebuilder/:
  • state.json: las ediciones del revisor, comentarios y orden de diapositivas, reflejados desde la página. Nunca lo escribas a mano.
  • review.json: tus respuestas, rondas e insignias de cambios. Escríbelo a través de sb.
• Cada carpeta de presentación es un repositorio git. Los archivos PDF, zip y PPTX están ignorados.

La página

• Cuatro vistas: Enfoque (F), Desplazamiento (S), Clasificador (G) y Verificaciones (C). La tira de película a la izquierda se reordena arrastrando.
  • En Enfoque y Desplazamiento, el cuadro de comentarios se encuentra debajo de cada diapositiva, con tu respuesta debajo. La barra derecha contiene las notas de la diapositiva y lo que cambió.
  • Verificaciones tiene cinco comprobaciones: teclas 1 a 5: la prueba de 5 segundos (primera impresión), la prueba de 10 segundos (legibilidad; un fallo deja un comentario en la diapositiva para la siguiente ronda), flujo horizontal (solo los títulos, editables en el lugar), flujo vertical (el título primero, el cuerpo oculto hasta que se revela) y Guías.
  • Los comentarios pueden provenir de Verificaciones: "Prueba de cinco segundos: …" y "Prueba de diez segundos: …" después de una prueba cronometrada fallida, y "Guías: …" de Preguntar a Claude para arreglar en Verificaciones › Guías, nombrando qué rompe la diapositiva. Arregla la diapositiva para que pase, como cualquier comentario.
  • H oculta todo excepto los títulos. ? lista cada atajo de teclado.
• Agregar una diapositiva (N, "+ Diapositiva", o el + entre diapositivas) sugiere diseños y puede agregar uno que la presentación lleve. Su prompt de Copia te da el archivo de la presentación, la posición y lo que debería decir la diapositiva. Cuando un prompt dice "Acabo de agregar una diapositiva … (LIBRARY['id'])", rellena esa diapositiva; cuando dice "agregar una nueva diapositiva …", constrúyela en el archivo de la presentación en esa posición.
• Cuando el revisor edita un título en Verificaciones, eso es una edición en línea: intégrala como cualquier otra.
• Ocultar trabajo del cliente (un interruptor en el panel de control, settings.json en la carpeta de presentaciones) es para grabación o compartir pantalla. Con él activado, el servidor omite las presentaciones marcadas como client y las versiones listadas en clientVersions. Nunca muestres nombres de clientes en pantalla cuando esté activado.

Una ronda ("procesar cambios")

1. cd a la carpeta de la aplicación.
2. ./sb comments <presentación> lista los comentarios sobre los que actuar, numerados como en la presentación. Los borradores se omiten. ./sb edits <presentación> muestra las ediciones de texto en línea del revisor y los movimientos de diapositivas. Ambos leen del disco, por lo que no necesitas su pestaña del navegador.
3. ./sb status <presentación> "Leyendo tus 9 comentarios" --done 0 --total 9. El revisor ve esto en vivo en la barra superior. Actualízalo a medida que avanzas.
4. Para cada comentario:
   • ./sb working <presentación> <diapositiva>.
   • Realiza el cambio en el archivo de la presentación.
   • ./sb reply <presentación> <diapositiva> done "una oración simple sobre lo que cambió".
   • Si necesitas la decisión del revisor, usa question en lugar de done. Para algo que deliberadamente dejaste sin cambios, usa skipped y explica por qué.
   • Un comentario a medio escribir recibe una respuesta question, no una suposición.
5. Incorpora las ediciones en línea del revisor en el archivo de la presentación (su edición gana). Git tiene la versión anterior.
6. Verifica cada diapositiva que tocaste:
   • ./sb shot <presentación> <ids…>, luego mira cada imagen.
   • ./sb audit <presentación> encuentra desbordamientos, etiquetas superpuestas y cualquier cosa que las Guías marquen.
   • ./sb comments <presentación> no debería mostrar nada nuevo y no manejado.
7. Finaliza:
   • ./sb export <presentación> escribe el siguiente PDF numerado desde el archivo de la presentación y mueve los anteriores a _archive/. Si el navegador aún contiene ediciones que no se han integrado, lo indica: intégralas primero. --with-edits exporta exactamente lo que muestra el navegador en su lugar.
   • ./sb round <presentación> --summary "…" --changed id="lo que cambió" … --export vN.
   • ./sb commit <presentación> "Ronda N: …".
   • ./sb idle <presentación>.
   • Dile al usuario dónde está el PDF.
8. La página se recarga sola una vez que el revisor deja de escribir. No recargues ni cierres su pestaña. En el chat: unas pocas líneas, más cualquier cosa que necesite su decisión.

Pueden llegar nuevos comentarios mientras trabajas. Ejecuta ./sb comments de nuevo antes de finalizar.

El revisor elimina los comentarios manejados con "Se ve bien". No los agregues a DONE_FB; esa lista es solo para copias abiertas fuera de Decks, como un archivo enviado a otra persona.

El archivo de la presentación

• Un archivo HTML autocontenido por presentación, con tres partes que editas:
  • contenido: entradas LIBRARY ('id': { cat, layout, title, …, notes }), agrupadas en partes por cat (las partes son CATS, nombradas en CAT_LABELS)
  • figuras: funciones FIGS que devuelven SVG en línea
  • versiones: PITCHES (cada una un nombre y una lista de ids de diapositivas)
• La versión predeterminada es el orden de LIBRARY dentro de cada parte. Para reordenar, mueve las entradas de LIBRARY. Un orden guardado que sea igual a un orden predeterminado antiguo sigue el archivo.
• Retira una diapositiva con alt:true (va al estante del Clasificador) y coloca su reemplazo justo antes. No elimines las diapositivas del usuario. Una versión alternativa de una diapositiva lleva prop:true, replaces:'…' (etiquetada "Propuesta").
• Una línea de fuente va en el pie de página mediante src:'Fuente: …', no en un subtítulo.
• Colores, fuente del título y logotipo: un bloque <style id="deck-theme"> en el archivo de la presentación, y LOGO para el logotipo de la presentación en img/. Cambia el estilo editando ese bloque, no diapositivas individuales. Sin LOGO, las diapositivas no tienen logotipo.
• Cambios visuales grandes (un nuevo diseño, un rediseño): muestra al usuario un mockup o dos opciones primero, luego construye.
• Cuando el usuario quiere un archivo para enviar a alguien, ese es el menú ⋯ › Copia para cliente: la versión en pantalla solo con diapositivas (sin notas, comentarios, diapositivas del facilitador, otras versiones ni edición), imágenes dentro, con un botón de Presentar. Copia editable es toda la presentación con notas y comentarios: nunca envies esa a un cliente.
• Las presentaciones se retiran del panel de control con ./sb hide <presentación> (vuelven con ./sb show). ./sb delete <presentación> --yes mueve una presentación creada por esta aplicación a la Papelera y solo elimina el registro de una presentación en una carpeta propia del usuario. Solo elimina cuando el usuario lo pida.
• Descargar imágenes o logotipos necesita la aprobación del usuario cada vez. Dile el nombre del archivo, la fuente, el tamaño y la licencia, y coloca el crédito en el pie de página.

El método

Decks está construido sobre el método que Paul Millerd enseña en StrategyU. Aplícalo a cada diapositiva que escribas o arregles. Si la habilidad strategy-slides está instalada, tiene la versión completa: úsala para historias, títulos y comentarios.

Responde primero. Encabeza con la recomendación, luego el contexto, luego la evidencia. Construye hacia la recomendación (situación y complicación, luego las ideas clave) solo para una audiencia escéptica.

Presentación fantasma primero. Antes de construir cualquier cuerpo de diapositiva, escribe cada título de acción en orden y léelos como un párrafo. Si el párrafo no presenta el argumento, corrige los títulos o el orden ahora; es el punto más barato para arreglar la historia. Anota lo que cada cuerpo debe mostrar para probar su título.

Flujo vertical: el título es la conclusión, y el cuerpo lo demuestra.

• Cada título es un título de acción: una oración completa que expresa el punto. "Los ingresos del tercer trimestre crecieron un 22%, impulsados por la expansión empresarial", nunca "Ingresos del T3".
• Supera los títulos vagos. "La empresa está mejorando" es el paso uno; "La rentabilidad aumentó por primera vez en 5 años debido a inversiones en la cadena de suministro" es a dónde llegar.
• Sin cuadros de "conclusión clave" ni tiras de resumen al final. La idea principal lidera la página.
• Usa verbos simples con sus objetos naturales. No personifiques los datos ni fuerces metáforas sobre los números. Sin fragmentos de coma pivote ("Un modo de pensar, cuando el trabajo necesita dos"). Máximo dos líneas. Léelo en voz alta: debería sonar como algo que una persona le diría a un colega.
• Los títulos solo de conteo están en blanco. "Tres riesgos y cómo los cubrimos" se convierte en el hallazgo: "La exposición real es el servicio de la Costa Oeste, no la capacidad del almacén."
• Las portadas, los separadores de secciones y el separador del apéndice están exentos. La diapositiva de cierre no: "Aprobar antes del 14 de marzo y salimos de ambos arrendamientos antes de que se renueven", no "Próximos pasos".

Flujo horizontal: los títulos solos cuentan la historia. Léelos en orden (Verificaciones › Flujo horizontal). Si no tienen sentido sin los cuerpos de las diapositivas, corrige los títulos o el orden.

Una idea por diapositiva. Si una diapositiva necesita "y también", necesita ser dos diapositivas.

Las pruebas de cinco y diez segundos tratan sobre la legibilidad. Una diapositiva presentada transmite su punto en cinco segundos. Una diapositiva que la gente lee se puede asimilar en diez: un punto principal, una jerarquía legible, un gráfico cuya forma se lee sin estudio. Muros de texto, un número clave enterrado en una tabla densa y varias ideas no relacionadas en una diapositiva fallan todas.

"¿Y qué?" es una prueba separada. Tres casillas ordenadas que dicen Innovación, Excelencia, Crecimiento pasan la prueba de diez segundos y fallan "¿Y qué?" (síndrome de la diapositiva bonita). Cada diapositiva le dice a la audiencia qué pensar. Mantén los dos hallazgos separados cuando des comentarios.

Los gráficos demuestran el título. Escribe el mensaje antes de dibujar el gráfico. Las barras, columnas y líneas cubren casi todo; nunca uses un gráfico circular. El número que importa es la marca más prominente, cualquier cosa que el título nombre (una recesión, un punto de inflexión) está marcada en el gráfico, y todo lo que no respalde el título se elimina. Los datos inciertos llevan una etiqueta "Ilustrativo" y una nota sobre las suposiciones.

El resumen ejecutivo es la diapositiva más importante: la recomendación como título, y tres ideas con una línea de evidencia cada una. Usa separadores de secciones solo en presentaciones largas (20+ diapositivas) con secciones distintas.

Presentada o leída. Presentada: menos de 20 palabras en el cuerpo, una idea, imágenes grandes. Leída: más texto está bien, con palabras clave en negrita, y cada diapositiva se sostiene por sí sola porque será reenviada.

Dar comentarios sobre una presentación. Lee toda la presentación primero. Luego da, en orden: la historia (los títulos en secuencia, lo que dicen y lo que falta o está fuera de orden); las diapositivas que tienen un problema, con la corrección (escribe el nuevo título cuando el título sea el problema); y los tres cambios que más importan, con el argumento y el orden antes que las fuentes y los colores. Si el argumento no se sostiene, dilo primero. Verifica cada número de diapositiva antes de citarlo.

Escritura. Verbos activos, contracciones y números en lugar de adjetivos. Nunca: profundizar, panorama, apalancar, utilizar, crucial, fundamental, robusto, sin fisuras, transformador, subrayar, adicionalmente, además, asimismo. Máximo una raya em por diapositiva.

Reglas de estilo de diapositivas

Además del método:

• Sin líneas pequeñas, atenuadas o en cursiva en la parte inferior de tarjetas o cuadros. Incorpora cualquier cosa importante al elemento al que pertenece.
• Sin rejillas de tarjetas idénticas. Dibuja la relación en su lugar: un proceso, espectro, escalera, gráfico o mapa.
• Las instrucciones son una oración simple. Las preguntas de reflexión son simples y tratan sobre el propio trabajo de la audiencia.
• Los horarios de la agenda en bloques de 5 minutos redondeados.
• Usa el material, diagramas y redacción del usuario antes de inventar marcos. Al cortar, corta primero las diapositivas inventadas y mantén completos los pares de construcción/remate.
• Marca el texto que redactaste en las notas, para que el usuario pueda reemplazarlo.
• Las citas y los números provienen solo de fuentes que abriste en la sesión, citados exactamente y atribuidos a quien realmente los dijo.
• Todo pasa Verificaciones › Guías: el borde protegido, títulos de dos líneas, nada por debajo de 12 px, como máximo cuatro tamaños de texto en una diapositiva. Estas son pautas, no reglas; corrige lo que sb audit liste, o explica por qué una diapositiva es una excepción.

Comenzar una nueva presentación

El usuario inicia presentaciones desde el formulario Nueva presentación del panel de control, en dos pasos. Paso 1: un nombre, qué están construyendo (una presentación, una formación, una charla, una propuesta o una presentación en blanco) y las piezas para construir junto con ella. Paso 2: para quién es, qué saben y les importa, el punto principal, y opcionalmente la duración, el tipo de audiencia, la estructura, la densidad, los colores, la fuente del título, el logotipo y las notas. Crear presentación hace la carpeta, le da su propio prefijo de almacenamiento, la agrega a decks.json, inicia su historial git, escribe el resumen en BRIEF.md, copia un prompt a su portapapeles y abre la presentación. Cuando pegan ese prompt:

1. Lee BRIEF.md en la carpeta de la presentación y adapta la plantilla a él antes de escribir diapositivas. La plantilla es un punto de partida, no una forma fija:

   • Cómo se usará. Presentada: una idea por diapositiva, tipo grande, poco texto; debe pasar la prueba de 5 segundos. Enviada para leer: cada diapositiva se sostiene por sí sola con un cuerpo más completo; debe pasar la prueba de 10 segundos. Presentada, luego enviada: diapositivas presentables, con el detalle en las notas o un apéndice.
   • Audiencia y lo que saben. Adapta el vocabulario, los ejemplos y cuánto explicas; los ejecutivos obtienen la respuesta primero.
   • Estructura. Responde primero: la recomendación, luego las razones. Situación, complicación, resolución: en ese orden. Una historia en algunas partes: secciones con separadores. Enseñar, practicar, reflexionar: módulos con ejercicios y preguntas de reflexión.
   • Densidad. Escasa, equilibrada o detallada, como dicen las palabras.
   • Cualquier cosa que se deje en blanco es tu decisión; usa el sentido común y el estilo de otras diapositivas.

2. Crea la estructura de la presentación: las partes que necesitas, los separadores de secciones (si la presentación es larga), la diapositiva de resumen ejecutivo y una diapositiva de cierre. Al menos el resumen y el cierre usan la plantilla de la presentación.

3. Escribe los títulos de acción y verifica el flujo horizontal (primera prueba: ¿funciona la historia con solo los títulos?).

4. Agrega el contenido del cuerpo para probar los títulos, siguiendo las reglas de estilo (#estilo).

5. Verificaciones: ./sb audit (Guías, superposiciones, desbordamientos), ./sb shot (captura las tres primeras diapositivas y cualquier cosa inusual), y léelas en el navegador. Si el usuario no te ha dado comentarios, pídelos.

Cuando el usuario dice "comenzar de nuevo" o comienza una presentación desde el panel de control, lee el resumen y construye la presentación de inmediato. No pidas confirmación a menos que el resumen haya cambiado.

Construir una presentación desde cero (sin el panel de control)

Cuando el usuario describe lo que quiere pero no usó el formulario Nueva presentación:

1. Pregunta o infiere la audiencia, el punto principal y el uso (presentada, leída o ambas).
2. Escribe un resumen corto, muéstraselo al usuario y pregúntale si se ajusta. Si dice que sí, construye la presentación.
3. Para construirlo, haz que sb lo cree: ./sb new <nombre> en la carpeta de la aplicación. Luego estructura, llena diapositivas, y edita como de costumbre. Siempre edita el archivo de la presentación; nunca pases contenido como parte de un comando sb.