Communitygithub.com

work-brochure

Guía al usuario a través del trabajo finalizado como un folleto HTML visual (diagramas de flujo, capturas de antes/después de la aplicación real, decisiones, mapas de archivos, extractos de diferencias, evidencia de verificación), además del resumen de texto normal en el chat. Funciona en cualquier repositorio.

¿Qué es work-brochure?

El skill 'work-brochure' está diseñado para complementar el resumen textual habitual de un agente de IA (como Claude Code, Cursor o Codex) con un folleto HTML visual autónomo que detalla el trabajo completado. Su objetivo es que alguien que no estuvo en la sesión entienda qué cambió y por qué en menos de dos minutos de desplazamiento. El agente primero redacta el resumen normal en el chat, luego recopila datos reales (commits, diffstat, cambios no confirmados, información de PR) mediante un script auxiliar (`gather.sh`). Para cambios visibles en la interfaz de usuario, captura la aplicación real (después y, opcionalmente, antes) y las incrusta como imágenes optimizadas. Para cambios no visuales, usa diagramas y resultados reales de comandos. Luego construye una página HTML desde una plantilla que incluye: un héroe con el resultado y estadísticas, una sección de decisiones, un mapa de archivos, extractos de diferencias anotados, diagramas Mermaid (hand-drawn) y una lista de verificación con chips de estado (aprobado/fallido/no verificado). La página se guarda en `.claude/work-briefs/` y se comparte como un enlace en el chat y como un Artefacto privado si la herramienta está disponible. El skill funciona en cualquier repositorio y se activa automáticamente después de abrir un Pull Request, al finalizar una característica, corrección o elemento de trabajo, o cuando el usuario lo solicita explícitamente. Se omite para cambios triviales de una línea y preguntas/respuestas puras.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lincolncrooks/work-brochure/tree/HEAD/skills/work-brochure

Preguntar en tu IA favorita

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

Documentación

Folleto de trabajo

Después de finalizar una pieza de trabajo, el usuario quiere dos cosas:

  1. El resumen normal en el chat, exactamente como lo escribirías de todos modos (qué cambió, en qué estado se encuentra, qué no está hecho). Este skill nunca lo reemplaza ni lo acorta.
  2. Un folleto: una página HTML autónoma que recorre visualmente el mismo trabajo, para que puedan abrirla junto al chat y entender el cambio a través de diagramas, capturas de pantalla y código anotado en lugar de párrafos.

El folleto debe ser fiel al código. Cada afirmación, número, ruta de archivo y captura de pantalla proviene del diff real, los comandos que ejecutaste y la aplicación que viste. Nunca inventes una prueba que no se ejecutó ni un resultado que no viste.

Pasos

1. Escribe primero el resumen del chat

Termina el trabajo como de costumbre, incluyendo tu resumen de texto normal y wrap_up (si la aplicación lo tiene). Luego construye el folleto. Si el usuario solo pidió el folleto de un trabajo anterior, salta directamente al paso 2.

Después de abrir un PR (el hook PostToolUse del plugin, o uno en tu configuración, agrega un recordatorio después de gh pr create), construye el folleto para ese PR con gather.sh --pr <N> en el mismo turno, y pon el enlace del folleto en tu mensaje de cierre. No edites el cuerpo del PR para agregarlo a menos que el usuario lo pida. Omítelo solo si el PR es trivial (error tipográfico, cambio de versión).

2. Recopila los hechos

Ejecuta el ayudante desde la raíz del repositorio (imprime commits, un diffstat por archivo agrupado por carpeta, cambios no confirmados e información del PR):

bash <skill-dir>/scripts/gather.sh            # esta rama vs main + no confirmados
bash <skill-dir>/scripts/gather.sh A..B       # cualquier rango de git (ej. trabajo ya fusionado)
bash <skill-dir>/scripts/gather.sh --pr 51    # un PR de GitHub

Luego lee las partes del diff que importan (git diff <rango> -- <ruta>), no todo. También recopila de esta conversación:

  • Por qué: el problema o solicitud en los propios términos del usuario.
  • Decisiones: opciones que sopesaste y por qué elegiste esta.
  • Verificación: comandos ejecutados y su salida real, capturas de pantalla tomadas, lo que verificaste en el navegador o simulador, y lo que no pudiste verificar.
  • Cabos sueltos: seguimientos, riesgos, cualquier cosa pendiente.
  • Necesita al usuario: cualquier cosa que solo ellos puedan decidir, verificar visualmente o aprobar.

3. Captura la aplicación real (cuando el cambio es visible)

Si el cambio se muestra en una interfaz de usuario, el folleto debe mostrar la aplicación real, no una descripción de ella.

  • Después: toma una captura de pantalla de la aplicación en ejecución en la(s) pantalla(s) modificada(s) con las herramientas de vista previa (preview_start con el proyecto launch.json server, navega, computer {action: "screenshot"}), o el simulador de iOS screenshot. Captura tanto el ancho de escritorio como el de teléfono cuando el diseño cambió.
  • Antes: si la diferencia es el punto, haz checkout de la revisión base en un worktree temporal en el scratchpad (git worktree add <scratchpad>/before <base>), sírvelo en un puerto diferente, captura la misma vista, luego elimina el worktree (git worktree remove). Omite esto cuando el cambio es puramente aditivo o un "antes" no aporta nada.
  • Guarda las capturas de pantalla como archivos en el scratchpad, redúcelos (sips -Z 1400 -s format jpeg -s formatOptions 78 in.png --out out.jpg) e incrústalos como URIs data:. Mantén toda la página por debajo de ~8 MB.
  • Para cambios de video/animación, incrusta algunos fotogramas fijos (ffmpeg -ss <t> -i clip.mp4 -frames:v 1 -vf scale=900:-1 still.jpg) o una tira de fotogramas, además de los números medidos.
  • Los cambios no visuales (scripts, datos, backend) obtienen diagramas y resultados reales en lugar de capturas de pantalla.

4. Planifica la historia, luego elige los recursos visuales

Ordena la página como al usuario le gustaría que se le explicara: el resultado primero, luego cómo funciona, luego el detalle. Elige los recursos visuales según lo que cambió. Prefiere una imagen donde explique más rápido que el texto; mantén la prosa en pies de foto cortos y párrafos de una a tres oraciones.

Qué cambióRecurso visual a usar
Lógica, un pipeline, una regla de decisiónflowchart de Mermaid del nuevo flujo; resalta los nodos nuevos/cambiados con classDef changed
Solicitudes entre partes (UI → API → almacenamiento)sequenceDiagram de Mermaid
Estructura (módulos, archivos, forma de datos)Mapa de archivos con barras +/−; graph de Mermaid de cómo se conectan las partes; una tabla de campos antes/después
UIPar de capturas antes/después; anota con llamadas numeradas colocadas sobre la imagen
Números (tiempos, tamaños, conteos, rendimiento)Gráfico de barras SVG en línea dibujado a escala, antes vs después
Estado o ciclo de vidastateDiagram-v2 de Mermaid
Una secuencia de trabajo (migración, cambio de varios pasos)Pasos numerados de recorrido (solo cuando el orden es real)
Código claveExtractos de diff cortos (5–25 líneas) con las líneas importantes marcadas, dentro de <details> para que no dominen

Apunta a al menos tres recursos visuales distintos para un cambio de tamaño de funcionalidad, y al menos uno para cualquier cosa más pequeña. Los diagramas deben describir el mecanismo real (nombres de funciones reales, nombres de archivos, valores), no cajas genéricas.

5. Construye la página a partir de la plantilla

Copia <skill-dir>/template.html y complétala. Ya contiene el aspecto de bloc de dibujo (un tema claro a propósito: fondo de papel cuadriculado, encabezados escritos a mano, tarjetas dibujadas a lápiz, diagramas dibujados a mano), el diseño y cada componente listado arriba. No agregues un modo oscuro ni cambies el aspecto a menos que el usuario lo pida. Reglas:

  • Mantén el bloque <style> y el script cargador de Mermaid; reemplaza el contenido de ejemplo. Elimina las secciones que no apliquen en lugar de dejarlas delgadas (ej. sin "Antes → después" para una refactorización pura).
  • <title>: el nombre de la funcionalidad, de dos a cuatro palabras (ej. "Lógica de reintento de checkout"), no "Resumen de trabajo: …".
  • Héroe: una oración sobre el resultado, la línea de metadatos (rama, enlace del PR, fecha) y la tira de estadísticas (archivos, líneas +/−, commits, pruebas aprobadas). Calcula los números de gather.sh, no estimes.
  • Necesita tu aporte (nota adhesiva debajo del héroe): solo solicitudes reales que esperan al usuario, una línea cada una, indicando dónde mirar. Como máximo tres. Elimina toda la nota cuando no haya ninguna; nunca la rellenes.
  • Por qué de esta manera (tabla de decisiones): de dos a cuatro opciones que realmente se sopesaron en la sesión, una marcada como Elegida, una compensación de una línea cada una. No inventes alternativas para llenar; si no se tomó una decisión real, elimina la sección.
  • Mantén la página esbelta: estas dos más las secciones que apliquen. No agregues secciones más allá de la plantilla.
  • Mapa de archivos: una fila por archivo significativo (agrupa archivos generados/binarios en una fila), anchos de barra +/− como porcentaje del total del archivo más grande, más una línea en lenguaje natural sobre por qué cambió.
  • Extractos de diff: escapa <, >, &. Marca líneas con class="add", class="del" o class="hl" (línea importante sin cambios).
  • Mermaid va en <pre class="mermaid">, comenzando directamente después de la etiqueta con el bloque de configuración de la plantilla (--- / config: / look: handDrawn / theme: neutral / ---) para que se renderice dibujado a mano tanto como archivo local como en claude.ai. Mantén la línea classDef changed fill:#dfe7ff,stroke:#1f4fd1,stroke-width:2px de la plantilla. Escapa </> dentro de etiquetas como &lt;/&gt;, y usa class <ids> changed para lo que este trabajo agregó o cambió. Mantén cada diagrama en aproximadamente 5–9 nodos para que quepa en una pantalla: fusiona pasos consecutivos en un nodo con una línea de detalle <br/>, y divide un flujo más largo en dos diagramas. Usa flowchart LR para cadenas cortas, TD para las ramificadas.
  • Verificación: enumera cada comprobación con un chip de aprobado / fallido / no verificado y su evidencia (extracto de salida o captura de pantalla). Los elementos "No verificado" son obligatorios cuando existen.
  • Escribe de manera sencilla: oraciones cortas, los términos del usuario, sin relleno.

Guárdala como <repo-root>/.claude/work-briefs/<YYYY-MM-DD>-<slug>.html. Mantén esa carpeta fuera de git en cada repositorio sin tocar su .gitignore, agregándola al archivo de exclusión local una vez:

mkdir -p .claude/work-briefs && x="$(git rev-parse --git-common-dir)/info/exclude" && (grep -qxF '.claude/work-briefs/' "$x" 2>/dev/null || echo '.claude/work-briefs/' >> "$x")

6. Verifica una vez, luego entrega

  1. Ábrela una vez en el panel del navegador (preview_start con url: file://<ruta>, o el servidor estático del proyecto) y toma una captura de pantalla para confirmar que los diagramas se renderizaron y nada se desborda. Arregla lo que esa única vista muestre; no hagas un bucle.
  2. Muéstrala en el panel lateral: SendUserFile con display: "render".
  3. Publícala como un Artefacto privado (Artifact publicar con la ruta del archivo, icon: "document" y una descripción de una oración) para que sobreviva después de que se limpie un worktree. Esta es la copia persistente; los artefactos comienzan como privados. Si no hay ninguna herramienta de Artefacto disponible (ej. una sesión de terminal simple), omitelo y proporciona la ruta local.
  4. En el chat, después de tu resumen normal, agrega una línea con el enlace del folleto y la ruta del archivo local.

Actualización: si el usuario solicita cambios, edita el mismo archivo y vuelve a publicar en la misma ruta para que el enlace se mantenga.

Cómo se ve un buen folleto

  • Alguien que no estuvo en la sesión entiende qué cambió y por qué en menos de dos minutos de desplazamiento.
  • La primera pantalla responde "¿Qué es diferente ahora?" sin necesidad de desplazarse.
  • Cada diagrama, gráfico y captura de pantalla es de este cambio.
  • El estado honesto es visible: qué se verificó, qué no, qué queda.

Skills relacionados