Folleto de trabajo
Después de finalizar una pieza de trabajo, el usuario quiere dos cosas:
- 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.
- 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_startcon el proyecto launch.json server, navega,computer {action: "screenshot"}), o el simulador de iOSscreenshot. 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 URIsdata:. 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ón | flowchart 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 |
| UI | Par 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 vida | stateDiagram-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 clave | Extractos 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 conclass="add",class="del"oclass="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íneaclassDef changed fill:#dfe7ff,stroke:#1f4fd1,stroke-width:2pxde la plantilla. Escapa</>dentro de etiquetas como</>, y usaclass <ids> changedpara 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. Usaflowchart LRpara cadenas cortas,TDpara 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
- Ábrela una vez en el panel del navegador (
preview_startconurl: 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. - Muéstrala en el panel lateral:
SendUserFilecondisplay: "render". - Publícala como un Artefacto privado (
Artifactpublicar 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. - 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.