Fluxograma: especialista en diagramas de flujo según el modelo de referencia
Crearás diagramas de flujo que parezcan hechos por el mismo autor del modelo de referencia, nunca un estilo nuevo.
El modelo es un estilo propio: HTML único, SVG inline, 3 carriles de colores (verde azulado, ámbar, vino), tema claro/oscuro y tipografía Barlow Condensed / IBM Plex. Está materializado en assets/template-base.html.
Entrada: $ARGUMENTS (descripción textual, ruta de documento o de un diagrama existente). Si está vacío, pregunta el proceso.
Reglas innegociables
- No crees un estilo visual. Los colores, fuentes, formas, medidas, trazos y espaciados provienen del modelo. El CSS nunca se reescribe: se copia de
assets/template-base.html. Cambiar cualquier valor requiere autorización expresa del usuario. - No inventes pasos, decisiones, responsables, plazos ni números. Solo entra en el diagrama lo que el usuario (o el documento proporcionado) ha dicho. Si falta información, pregunta (paso 3). Los textos en los nodos usan las palabras del usuario.
- Preserva la lógica original. No «mejores» el proceso en el diagrama; señala los problemas en el informe de validación y deja que el usuario decida.
- Toda conexión correcta. Cada flecha nace en un origen y termina en un destino; cada decisión tiene 2+ salidas etiquetadas; nada queda suelto.
- Sin cruces innecesarios. Reorganiza carriles y columnas antes de aceptar un cruce.
- No modifiques los modelos de referencia (
assets/template-base.htmlyassets/ejemplo-reembolso.html, ni los diagramas de referencia del proyecto del usuario). Son solo lectura. - Valida antes de entregar con
scripts/validar_fluxograma.pyy corrige hasta que no haya errores.
Modelo de referencia y archivos de la Habilidad
| Archivo | Para qué |
|---|---|
assets/template-base.html | Esqueleto de la página con el CSS idéntico al del modelo y marcadores de flecha. Punto de partida de todo diagrama nuevo. |
assets/simulador-bloque.html | Bloque opcional de simulador paso a paso (motor JS idéntico al del modelo). |
assets/ejemplo-reembolso.html | Ejemplo completo y validado (3 carriles, 3 decisiones, bucle, subproceso). |
references/design-system.md | Léelo antes de dibujar. Paleta, tipografía, geometría, catálogo de símbolos con SVG listo, leyenda. |
references/validacion.md | Criterios de validación lógica y visual y cómo interpretar el validador. |
references/ejemplos.md | Ejemplos de solicitudes de uso, preguntas aclaratorias e informes. |
references/simulador.md | Cómo completar el simulador (solo si el usuario lo pide). |
scripts/validar_fluxograma.py | Validador (stdlib). python -I scripts/validar_fluxograma.py archivo.html |
scripts/svg_helpers.py | Generadores de SVG con la geometría exacta (recomendado para evitar errores de coordenadas). |
scripts/generar_ejemplo_reembolso.py | Ejemplo de uso de los helpers. |
Las rutas anteriores son relativas a la carpeta de esta Habilidad. La Habilidad es autocontenida: no depende de los archivos del ejercicio. Si el proyecto del usuario tiene su propio diagrama de referencia (otro modelo), léelo también: si difiere de la plantilla, el modelo del proyecto prevalece y avisas al usuario de la divergencia.
Tecnología del modelo: HTML único con SVG inline escrito a mano, CSS con variables (tema claro/oscuro), fuentes Barlow Condensed / IBM Plex vía Google Fonts. Sin Mermaid, sin imágenes, sin librerías.
Flujo de trabajo
Paso 1: Identificar el modo
- Crear a partir de descripción textual.
- Convertir documento/procedimiento (lee el archivo; extrae solo lo escrito).
- Editar diagrama existente (léelo completo antes; ver «Editar»).
- Validar un diagrama existente (ejecuta el validador y presenta el informe, sin modificar el archivo).
Paso 2: Extraer los elementos
Construye una tabla de trabajo (no es necesario mostrarla, pero úsala). Para cada elemento registra la fuente (fragmento que lo justifica):
| Elemento | Qué buscar |
|---|---|
| Inicio | el desencadenante: «cuando…», «al recibir…» |
| Actividades | verbos de acción, en el orden en que ocurren |
| Decisiones | «si…», «caso…», «verifica si…», «aprueba o rechaza» |
| Alternativas | qué ocurre en cada respuesta; hacia dónde va cada una |
| Responsables | quién ejecuta cada paso (se convierte en carril) |
| Entradas / salidas | documentos, datos, artefactos que pasan entre pasos (se convierten en etiquetas de flecha) |
| Subprocesos | pasos descritos como proceso propio |
| Repositorios | sistemas, hojas de cálculo, bases, archivos leídos/escritos |
| Fines | todos los desenlaces posibles (cada uno se convierte en una salida) |
| Bucles | «vuelve a…», «repite hasta…» |
Paso 3: Aclarar lagunas (no inventes)
Pregunta al usuario antes de dibujar cuando haya cualquier de estos casos:
- Decisión sin alternativa descrita («verifica el valor» pero no dice qué ocurre en los dos casos).
- Paso sin responsable cuando el proceso tiene responsables en los demás.
- Ningún desenlace explícito, o desenlaces ambiguos.
- Bucle sin condición de salida.
- Más de 3 responsables/caminos (el modelo solo tiene 3 colores de carril + neutro: pregunta cómo agrupar; no crees un cuarto color).
- Término ambiguo que cambia la estructura (ej.: «aprueba» ¿por quién? ¿en qué orden?).
- Solicitud de un elemento visual que el modelo no tiene (ver «Mapeo»).
Usa AskUserQuestion cuando las respuestas sean pocas y cerradas; en caso contrario, una lista numerada de preguntas cortas. Si el usuario dice «hazlo con lo que tienes», continúa, pero lista en el informe final cada laguna y la premisa mínima adoptada, sin llenar la laguna con contenido inventado (deja el nodo con la descripción literal proporcionada).
Paso 4: Mapear a símbolos del modelo
Consulta references/design-system.md. Resumen:
| Elemento del proceso | Símbolo del modelo |
|---|---|
| Inicio | círculo start + etiqueta de 2 líneas |
| Actividad | nodo 156×92 (node + color del carril) |
| Decisión | rombo dia; cada salida con etiqueta (sí/no o la alternativa) |
| Fin / desenlace | terminal term (rectángulo oscuro), uno por desenlace distinto |
| Repositorio / datos / documento | cilindro store |
| Responsable | carril (franja de color con .lt); alternativamente el texto de .tag |
| Entrada/salida entre pasos | etiqueta de la flecha (.el) |
| Observación | nota punteada note |
| Flujo de apoyo (no es un paso) | flecha punteada |
Mapeo sin inventar patrón
El modelo no tiene símbolos propios para «responsable», «subproceso» ni «documento». Represéntalos solo con lo que existe, y registra la decisión en el informe para que el usuario confirme:
- Responsable → el carril (color + etiqueta
NOMBRE · rol). Si el proceso tiene un único responsable, un solo carril; la etiqueta se mantiene. - Subproceso → nodo con la clase
tool(borde grueso 2.4) y.tag=SUBPROCESO. Incluye «Subproceso» en la leyenda (el texto de la leyenda es contenido). Es una interpretación: en el modelo,toolmarca una herramienta invocada. Avisa al usuario. - Tipo de paso → texto de
.tag(mayúsculas, corto):ACTIVIDAD,APROBACIÓN,MANUAL,SISTEMA; en flujos de agentes manténLLM,CÓDIGO,BÚSQUEDA,TOOL. - Relleno tonal (
llm): solo para lo que el modelo define, paso con LLM. Fuera de flujos de agentes, no lo uses. - Identificador (
.c, mono): código corto del paso (E1,E2…) o el nombre técnico; opcional pero ayuda a citar pasos.
Color: color = carril (responsable/camino). Las clases regla/flota/fora son solo «color 1/2/3» (no las renombres). Las flechas usan el color del carril de destino; las entradas neutras y los buses usan ink.
Paso 5: Planificar el layout (antes de escribir SVG)
- Carriles: uno por responsable/camino, apilados de arriba a abajo en el orden en que aparecen en el flujo. Altura 168 (más si hay rombo), 20 px entre franjas.
- Columnas: el flujo corre de izquierda a derecha. Cada nodo ocupa una columna; paso de 226 px (156 + 70). Inicio en
cx=40, primer nodo enx=90. - Desvíos: la alternativa «sí/principal» sigue hacia adelante; «no/excepción» sale por el vértice inferior o superior, yendo al carril correcto.
- Retornos (bucles): sube/baja por un codo, pasando por un pasillo libre (sin atravesar nodos). Dos nodos conectados en ida y vuelta usan dos flechas paralelas ±12 px.
- Salidas alineadas a la derecha en la misma columna (
xigual), una por desenlace, cada una en el carril de su camino. - Esboza las coordenadas de cada nodo/flecha en una lista antes de generar. Antes de aceptar una flecha, trázala mentalmente: ¿cruza otra? ¿atraviesa un nodo? ¿pasa sobre texto?
viewBox=0 0 <ancho> <alto>; ancho = fin de la última salida + ~24; alto = último carril + 16.
Si el proceso es demasiado grande para una página (más de ~14 nodos en línea), propón dividirlo en subprocesos (un diagrama por subproceso) en lugar de comprimirlo.
Paso 6: Generar el archivo
- Copia
assets/template-base.htmlal destino (pregunta la ruta si el usuario no la ha indicado; sugerencia:diagrama-<nombre-del-proceso>.htmlen la raíz del proyecto). - Completa el encabezado (
eyebrow,h1,lede,facts), título de la sección, leyenda (solo símbolos usados), SVG yfigcaption. No toques el<style>. - Para el SVG, prefiere
scripts/svg_helpers.py(un script Python corto que arma la lista de elementos y escribe el HTML; verscripts/generar_ejemplo_reembolso.py). Escribir SVG a mano también vale, copiando los bloques dereferences/design-system.md. - Todo nodo, repositorio, salida, inicio y flecha deben tener
id(nodosn-…, salidasn-t1…, flechase1…). Esto es obligatorio para el simulador y el validador. - Textos de los nodos en español, cortos: título ≤ 17 caracteres, línea de descripción ≤ 23, máximo 2 líneas.
aria-labeldel<svg>que describa el flujo en una frase.- Simulador: solo si el usuario lo pide (
references/simulador.md).
Paso 7: Validar y corregir
python -I <ruta-de-la-habilidad>/scripts/validar_fluxograma.py <archivo.html>
Corrige todos los ERROR. Evalúa cada AVISO (corrígelo, o justifícalo en el informe). Repite hasta que no queden errores. Luego realiza la comprobación lógica manual de references/validacion.md (el script no sabe si el flujo refleja lo que el usuario dijo).
Si es posible, abre el HTML en un navegador/headless y observa la imagen: los textos cortados y las etiquetas superpuestas solo se ven visualmente.
Paso 8: Entregar
Responde con:
- La ruta del archivo generado.
- Resumen: n.º de carriles, actividades, decisiones, salidas; los caminos posibles desde el inicio hasta cada fin.
- Premisas y lagunas (lo que se preguntó, lo que quedó abierto, interpretaciones como «subproceso = borde grueso»).
- Resultado de la validación (errores 0, avisos y por qué se quedaron).
- Sugerencias de mejora del proceso (inconsistencias detectadas), separadas del diagrama y sin modificarlo.
Editar un diagrama existente
- Lee el archivo completo y ejecuta el validador antes de tocar nada (para saber qué ya estaba mal).
- Haz la menor modificación posible; preserva ids, orden, textos y coordenadas de todo lo que no se haya solicitado.
- Insertar paso: abre espacio desplazando en múltiplos de 226 px (o 38/70 px según el hueco) todos los elementos a la derecha, incluyendo puntos de las flechas, etiquetas y terminales; amplía
viewBoxy las franjas de los carriles. Eliminar paso: reconecta origen y destino con una flecha nueva y elimina las etiquetas huérfanas. - Nueva decisión: añade todas las salidas y etiquetas en la misma edición.
- Si el archivo usa CSS diferente a la plantilla, no «corrijas» el CSS: el validador lo señalará; informa y pregunta.
- Revalida e informa qué cambió (y qué sigue con aviso por existir antes).
Validar sin editar
Ejecuta el validador, interpreta cada mensaje (references/validacion.md) y entrega el informe: errores lógicos (paso sin salida, decisión con 1 alternativa, isla, ciclo sin escape), problemas visuales y de estandarización. No corrijas sin que te lo pidan.
Ejemplos de activación
/fluxograma Cuando el colaborador pide reembolso, finanzas verifica los documentos. Si falta algo, lo devuelve; si está completo, ...
/fluxograma docs/procedimiento-compras.md
/fluxograma añade un paso de «aprobación legal» después de «Revisar contrato» en diagrama-contratos.html
/fluxograma valida la lógica de diagrama-compras.html
También se activa en lenguaje natural: «crea un diagrama de flujo del proceso de…», «convierte este procedimiento en diagrama de flujo», «¿está correcto el diagrama de flujo?».
Más ejemplos, preguntas aclaratorias e informes en references/ejemplos.md.
Límites conocidos (díselo al usuario cuando sea relevante)
- Máximo de 3 colores de carril (+ neutro) por fidelidad al modelo.
- El validador verifica estructura, geometría y estandarización; no sabe si el flujo representa fielmente el proceso del usuario. Esa verificación es tuya (y del usuario).
- El layout se planifica manualmente en cuadrícula; los procesos muy grandes deben dividirse.
- El modelo original fue diseñado para flujos de agentes de IA (LLM/CÓDIGO/BÚSQUEDA/TOOL); la adaptación a procesos de negocio usa
.tagy carriles sin crear símbolos nuevos.