birchloveye/draw-flowchart

Dibujar un póster de diagrama de flujo

El trabajo tiene dos mitades:

1. Tú conviertes el proceso en Mermaid. Esta es la parte que requiere criterio: cuáles son los estados, qué ramas faltan, dónde el proceso puede atascarse o romper una regla.
2. scripts/make_poster.py lo renderiza. No interviene ningún modelo, por lo que la misma entrada siempre produce el mismo póster.

<skill> abajo es la carpeta que contiene este archivo.

Flujo de trabajo

1. Comprende el proceso. Reformula el objetivo del usuario en una oración. Enumera ambigüedades, ramas faltantes ("¿qué sucede cuando este paso falla?") y pasos riesgosos. Pregunta al usuario solo sobre bifurcaciones que no puedas resolver por ti mismo.

2. Modélalo. Crea una carpeta para el diagrama (una carpeta por póster).

   • Con pstack (preferido). Si el skill statechart de pstack está disponible (Claude Code: /pstack:statechart; Cursor: /statechart; o su SKILL.md en disco), úsalo: escribe una especificación TLA+ con las reglas del usuario como INVARIANTES, ejecútala, lee report.md. Escribe el módulo de vista como se describe en references/pstack-statechart.md para que el diagrama se convierta limpiamente. Luego convierte:

     python3 <skill>/scripts/make_poster.py <carpeta> --from-statechart <statechart-out>/chart.mmd
     

     Esto escribe <carpeta>/flow.mmd e imprime los números de problema en orden, con la regla que cada uno rompe. Si el usuario ha pedido mantener pstack apagado, no lo actives; usa la siguiente ruta y dilo.
   • Sin pstack. Escribe <carpeta>/flow.mmd a mano siguiendo references/mermaid-rules.md. Marca cada problema que encuentres (una regla rota, un callejón sin salida, una rama faltante) con la clase breaks.
   • make_poster.py <carpeta> --init [--lang zh] escribe un flow.mmd y poster.json iniciales para editar.

3. Escribe <carpeta>/poster.json (references/poster-json.md): título, subtítulo, leyenda en el idioma del usuario y una tarjeta con una línea por cada nodo breaks, en el mismo orden que los números.

4. Renderiza.

   python3 <skill>/scripts/make_poster.py <carpeta>
   

   Primero verifica y no dibuja nada mientras haya errores. Corrige cada error; lee cada advertencia. Salida: poster.html (autocontenido, funciona sin conexión), poster.png (2x) y poster.svg.

5. Mira poster.png. Si no puedes ver imágenes, o para ahorrar costo, pásalo a un modelo más barato o subagente. Verifica:

   • cada nodo con anillo rojo tiene una línea de tarjeta y los números coinciden;
   • ninguna línea atraviesa texto ni parece estar conectada a la caja equivocada;
   • las etiquetas están en el idioma del usuario y son lo suficientemente cortas para leer;
   • nada importante está apretado. Correcciones: acorta etiquetas, pon un espacio donde una línea debería dividirse, divide un diagrama grande en dos pósters, o sobrescribe el espaciado en poster.json style. Luego renderiza de nuevo.

6. Informa al usuario: primero la ruta del PNG, luego una línea por problema (la regla y cómo el proceso llega a ella), luego lo que el modelo omite. Menciona que poster.html tiene botones Exportar PNG/SVG.

Requisitos

• Python 3.8+ (librería estándar; Pillow se usa para reducir fotos si está instalado).
• Chrome, Edge o Chromium para exportar PNG/SVG. Si no se encuentra ninguno, poster.html se sigue escribiendo; establece CHROME en el binario del navegador para habilitar la exportación.
• Opcional: pstack (https://github.com/cursor/plugins/tree/main/pstack) para la verificación TLA+, que necesita Java 11+ y las herramientas TLA+ (ver references/pstack-statechart.md).
• Las fuentes son fuentes del sistema (macOS: American Typewriter, Baskerville, Songti, Kaiti; Windows y Linux usan Courier New / Georgia / SimSun / Noto Serif CJK como alternativa). En Linux instala una fuente CJK como Noto Serif CJK para chino.

Límites

• Solo diseño de arriba a abajo.
• No hay estados compuestos, regiones paralelas, notas ni subgrafos. Para salida de statechart, usa una vista plana (state() devuelve una cadena).
• Funciona mejor con 15–25 cajas; por encima de 30 la verificación advierte. Divide procesos más grandes en varios pósters.
• El diseño automático ocasionalmente coloca una línea cerca de una caja no relacionada. Por eso existe el paso 5.

Ejemplo

examples/paper-submission/ en el repositorio: un modelo TLA+ de una presentación a una revista (statechart/), el flow.mmd convertido, poster.json y el póster renderizado. examples/paper-submission-zh/ es el mismo modelo con una vista en chino.