CommunityProgramación y desarrollogithub.com

sheets-to-playbook

Convierte una carpeta de fotos de hojas de trabajo en papel de un taller o sesión comunitaria (más fotos de talones de tarjetas de compromiso y notas de voz opcionales) en un borrador de sitio web de libro de jugadas, verifica cada línea contra las fotos y lo publica.

¿Qué es sheets-to-playbook?

Esta habilidad para Claude Code automatiza la transformación de fotografías de hojas de trabajo físicas, talones de tarjetas de compromiso y notas de voz en un sitio web de "playbook" (libro de jugadas) listo para publicar. Está diseñada para talleres o sesiones comunitarias donde los participantes escriben ideas en papel y se toman fotos. El flujo de trabajo consta de seis etapas: preparación (rotación de fotos, conversión HEIC, transcripción de voz con Whisper), etiquetado y verificación de cobertura (asignar fotos a mesas, detectar hojas faltantes o borrosas), transcripción de cada mesa (usando subagentes paralelos para leer escritura a mano siguiendo estrictamente el formato RAW), redacción del playbook (generar `session.json`), verificación y compilación (asegurando que cada línea se pueda rastrear a una foto o nota de voz), y publicación (generar un sitio estático). La habilidad enfatiza la precisión: nunca inventa contenido, marca palabras ilegibles con `[?palabra]` y requiere pasar la verificación antes de publicar. Funciona exclusivamente con Claude Code y requiere tener el repositorio clonado localmente.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Chris-Keene/sheets-to-playbook/tree/HEAD/.claude/skills/sheets-to-playbook

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Sheets to playbook (Hojas a libro de jugadas)

Repositorio: la carpeta que contiene ingest/ingest.py (el proyecto actual, si Claude Code se abrió en el clon). Todas las rutas a continuación son relativas a él. Lee ingest/RAW_FORMAT.md antes de la etapa 3: contiene el formato de transcripción y las reglas para escribir el libro de jugadas.

El objetivo es la velocidad el día del evento sin inventar nada. Cada línea del sitio web debe rastrearse hasta una foto o una nota de voz; ingest.py verify lo aplica.

Informa al usuario de lo que estás haciendo en cada etapa con una o dos líneas. Los tiempos de las etapas a continuación son guías aproximadas para una docena de mesas.

Antes del evento, playbook.config.json debe nombrar a los organizadores y dar la dirección web del libro de jugadas (allí apunta el código QR de la tarjeta de compromiso). Si aún tiene los valores predeterminados neutrales, dilo, pero continúa: la configuración solo cambia nombres y colores, nunca el contenido. --config <archivo> en verify, draft y publish selecciona un archivo de configuración diferente.

1. Preparar (1 a 2 minutos)

python3 ingest/ingest.py prepare "<carpeta>"
python3 ingest/ingest.py transcribe      # solo si la carpeta tiene notas de voz; ejecútalo en segundo plano

prepare crea una nueva ejecución en runs/ (y apunta runs/latest a ella): fotos rotadas verticalmente, HEIC convertido, una puntuación de nitidez por foto, mosaicos de 2x2 para lectura cercana, hojas de contacto en contact/, y notas de voz convertidas a WAV de 16 kHz. transcribe usa Whisper local (small.en, sin conexión una vez descargado) y adivina la mesa de cada nota por "Mesa siete…" al inicio.

Un segundo lote (más fotos, o las tarjetas, después de que la primera mitad esté en marcha): python3 ingest/ingest.py prepare "<carpeta>" --into <ejecución> las agrega a la misma ejecución. Los nuevos ID continúan desde el último (P022…), las etiquetas y los archivos sin procesar se mantienen, y los archivos que ya están en la ejecución se omiten. Luego etiqueta solo los nuevos ID.

2. Etiquetar y verificar cobertura (unos 5 minutos; haz esto primero, es crítico en tiempo)

Mira cada hoja de contacto (contact/sheet-*.jpg) y, donde una miniatura no esté clara, la foto en view/. Escribe labels.json en la carpeta de la ejecución:

{"photos": {"P001": {"table": 7, "sheet": "S2"}, "P014": {"kind": "stubs"}, "P020": {"kind": "other", "note": "foto de la sala"}},
 "audio":  {"A01": {"table": 7, "by": "speech"}}}
  • Cada hoja lleva un código impreso en la esquina inferior (S1, S2, S3, SS) y encabezados impresos; el número de mesa está escrito a mano por el líder de la mesa, en el círculo superior derecho y junto al código (S2 · Mesa 7). Los encabezados predeterminados del kit: S1 "¿Dónde se atasca el apoyo?", S2 "¿Qué ha ayudado o no?", S3 "¿Qué podrían probar ahora las personas y cómo se mantiene?", SS la hoja lateral "¿Has escuchado algo bueno? Escríbelo aquí." (Citas · Preguntas · Recursos). Si los organizadores cambiaron las preguntas, guíate por el código impreso. Cuando el círculo y la esquina no coinciden, el color del bolígrafo y el contenido lo resuelven: revisa las otras hojas de la mesa.
  • Mantén las etiquetas de audio que transcribe ya haya completado, después de verificarlas con la primera línea de la transcripción.
  • Dos hojas diferentes con el mismo código y número de mesa (status lista cualquier hoja con más de una foto: verifícalas): si los países y el contenido se superponen, es una mesa que usó dos copias; etiqueta ambas con el número y el transcriptor transcribe ambas. Si son claramente dos mesas, asigna a la segunda un número de repuesto a partir del 91, agrega "note": "escribió 22; segunda mesa" e informa al usuario. Cualquiera de las mesas puede ser "la segunda": elige una y describe ambas en las notas (sector, color de bolígrafo) para que la revisión pueda distinguirlas.
  • Un primer plano sin número de mesa en el encuadre (solo la casilla de recuento, por ejemplo): etiquétalo con la hoja que coincide y agrega "note": "mesa inferida de <lo que coincidió>".
  • Dos hojas en una foto (sujetadas una al lado de la otra): etiquétala con "sheet": ["S2", "S3"] para que status la cuente para ambas, y dilo en una note para que el lector sepa qué mitad es cuál.
  • prepare no puede enderezar una foto que está al revés en el encuadre (no hay una marca de rotación que leer). Los lectores se las arreglan, pero dilo en una note. Las fotos de tarjetas tienen una puntuación de nitidez más baja que las hojas (tarjeta lisa, bolígrafo fino), así que revisa una tarjeta MARCADA COMO BORROSA en view/ antes de pedir que la tomen de nuevo.

Luego ejecuta python3 ingest/ingest.py status (agrega --tables <n> si no hubiera 12 mesas) e informa al usuario de inmediato sobre cualquier hoja FALTANTE o BORROSA. Las hojas de contacto también etiquetan BAJA RESOLUCIÓN (reenviado por una aplicación de mensajería: está bien si la escritura es grande) y OSCURA (generalmente se lee bien): menciónalas, pero no requieren repetir la foto. Idealmente, esta verificación ocurre mientras las hojas aún están en la pared y se pueden fotografiar nuevamente.

3. Transcribir cada mesa (en paralelo, unos 5 a 10 minutos)

Genera un subagente por mesa (herramienta Agent, general-purpose, en segundo plano, todo en un mensaje), más uno para los talones de tarjetas si los hay. No degrades el modelo: la precisión de la escritura a mano es donde importa. Cada mensaje debe ser independiente e incluir:

  • La ruta absoluta del repositorio, la carpeta de la ejecución, el número de mesa, sus ID de foto (view/<id>.jpg y los mosaicos listados en manifest.json), y la ruta de su transcripción de voz si la hay.
  • "Lee ingest/RAW_FORMAT.md, etapa 1, y síguela exactamente. Escribe raw/T<nn>.json en la carpeta de la ejecución, luego ejecuta python3 ingest/ingest.py verify --run <ejecución> y corrige cualquier error que informe sobre tu archivo. Responde con un breve resumen: elementos por hoja, cada entrada unclear, y cada palabra tachada que hayas omitido."
  • Para talones: escribe raw/commitments.json como se describe al final de la etapa 1, incluyendo la línea opcional de Nombre y Organización de la tarjeta exactamente como está escrita, y siguiendo las reglas de tarjetas allí (tarjetas sin rasgar, firmas, una tarjeta en dos fotos).

Mientras se ejecutan, lee tú mismo las transcripciones de voz (si las hay) para conocer la sala antes de escribir.

4. Escribir el libro de jugadas (unos 10 a 15 minutos)

Sigue la etapa 2 de RAW_FORMAT.md. Escribe <ejecución>/session.json con meta.status: "draft". Inicia meta desde examples/session-template.json y completa los detalles del propio evento (nombre del evento, fecha, lugar) según lo que te diga el usuario; establece people en el recuento real de asistentes si lo saben. Nunca adivines estos: deja un campo como está en la plantilla y enuméralo para el usuario.

5. Verificar, corregir, compilar el paquete de revisión

python3 ingest/ingest.py verify --links
python3 ingest/ingest.py draft            # <ejecución>/playbook-draft.html: recuadros discontinuos = vacíos, etiquetas = fuentes
python3 ingest/ingest.py review           # <ejecución>/review.html: cada elemento junto a sus fotos

Corrige cada error (una línea que no se puede rastrear, una cita que se desvió, un nombre que se quedó) y vuelve a ejecutar hasta que verify pase. Las advertencias son para la revisión humana: repórtalas, no las ocultes.

Luego entrega al usuario el resumen de la revisión: los desafíos y qué mesas se fusionaron, cada lectura unclear con su ID de foto, cada palabra tachada que un lector omitió, elementos sin procesar no utilizados, problemas de enlaces y cualquier cosa sobre la que no estuvieras seguro de cómo agrupar. review.html muestra las notas de cada lector y el recuento "¿Quién está en esta mesa?" debajo de cada mesa. Abre review.html y playbook-draft.html para ellos.

¿Muchas palabras inciertas? La aplicación de revisión es más rápida que leer review.html de arriba a abajo: python3 tools/review/make_review.py --run <ejecución> compila <ejecución>/review/index.html, una tarjeta por lectura incierta con un primer plano de la escritura a mano. El usuario confirma o corrige cada una, guarda un archivo de decisiones, y python3 tools/review/apply_review.py --run <ejecución> <decisiones.json> escribe las lecturas de nuevo en los archivos sin procesar y en session.json. Vuelve a ejecutar verify y draft después. Las preguntas que no son una palabra incierta (una marca que podría ser un tachón, si fusionar dos mesas, si nombrar un recurso) van en <ejecución>/review/extra.json como comprobaciones y llamadas antes de compilar la aplicación; apply_review.py lista las respuestas en <ejecución>/review/to-action.md para que actúes sobre ellas. Consulta tools/review/README.md.

6. Publicar (después de que un humano haya revisado el borrador)

Aplica las correcciones de los revisores a session.json, establece meta.status en "final", luego:

python3 ingest/ingest.py publish --links  # se niega si algo no se puede rastrear o una sección está vacía

Esto escribe data/session.json y playbook/index.html. La carpeta playbook/ es un sitio estático: implementarlo en cualquier lugar es un paso separado, así que pregunta primero. Cada enlace en la página se maneja mediante script, por lo que también funciona si se abre directamente desde el disco.

Nunca

  • Añadir contenido de conocimiento general, incluso contexto "útil". Vacío es mejor que inventado.
  • Adivinar una palabra en silencio: usa [?palabra] o [ilegible] y enumérala.
  • Poner el nombre de una persona o empleador en la página publicada, excepto el propio nombre y organización de un compromiso que la persona escribió en su tarjeta (verify los verifica contra la tarjeta).
  • Publicar sin que verify pase y un humano haya leído el borrador.

Después

Las fotos y notas de voz pueden contener nombres y rostros. Una vez que el libro de jugadas esté finalizado, recuerda al usuario que elimine runs/*/audio, las fotos fuente y las notas de voz, y cualquier otra cosa que los organizadores acordaron no conservar.

Skills relacionados