Skill Generador de Diagramas de Decisión
Lee un archivo SKILL.md, extrae los datos estructurados en nodes.json y, mediante un script determinista, genera el diagrama de flujo en HTML.
División del trabajo
| Fase | Quién lo hace | Por qué |
|---|---|---|
| SKILL.md → nodes.json | IA | SKILL.md está en lenguaje natural, la semántica es inestable; la IA comprende el contexto |
| nodes.json → HTML | Script | El cálculo de coordenadas debe ser determinista, reproducible y alineado con los píxeles |
La IA solo produce datos estructurados, nunca coordenadas ni SVG; el script solo hace geometría, nunca adivina semántica.
Pasos de ejecución
1. Leer SKILL.md
Lee el SKILL.md especificado por el usuario. Si no se encuentra, pregunta al usuario la ruta.
2. La IA extrae nodes.json
Genera el JSON según el siguiente esquema. Cada arista saliente debe etiquetarse explícitamente con el campo side — esto es una decisión semántica de la IA, el script no la adivinará.
Estructura raíz
{
"title": "Nombre del Skill",
"subtitle": "Descripción opcional",
"nodes": [ ... ],
"edges": [ ... ],
"loops": [ ... ],
"legend": [ ... ]
}
nodes: obligatorio, array de nodosedges: obligatorio, array de aristas dirigidasloops: opcional, bucles en línea discontinua (ver más abajo)legend: normalmente se deja vacío[]para usar la leyenda por defecto
type de nodo
| type | Significado | Forma |
|---|---|---|
entry | Punto de entrada | Rectángulo redondeado |
decision | Punto de decisión (sí/no, tiene/no tiene) | Rombo |
process | Paso de proceso | Rectángulo redondeado |
output | Salida de informe/archivo | Rectángulo redondeado |
terminal | Terminación/salida por error | Rectángulo redondeado |
role de nodo (esquema de colores)
| role | Significado | fill / stroke |
|---|---|---|
ai | Razonamiento de IA / llamada a LLM | #E6F1FB / #185FA5 |
output | Informe / salida de archivo | #EEEDFE / #534AB7 |
decision | Punto de decisión | #FAEEDA / #854F0B |
script | Ejecución de script | #E1F5EE / #0F6E56 |
terminal | Terminación / error | #FCEBEB / #A32D2D |
Un nodo solo puede tener un role. Si un paso involucra múltiples tipos de trabajo de diferente naturaleza (que corresponden a diferentes roles), debe dividirse en varios nodos en serie. Por ejemplo, «Script toma línea base + IA completa análisis» no puede fusionarse en un solo nodo con role=ai, debe dividirse en dos nodos: role=script y role=ai.
side de arista (¡Clave!)
| side | Significado | Comportamiento en el layout |
|---|---|---|
bottom | Flujo principal hacia abajo | target está en la siguiente capa de from, cx hereda de from |
left | Rama izquierda de decisión / bifurcación izquierda | Decisión → misma capa, línea horizontal; normal → siguiente capa, línea poligonal ortogonal |
right | Rama derecha de decisión / bifurcación derecha | Igual que arriba, pero en dirección opuesta |
La interpretación semántica de side la realiza la IA:
- Rombo de decisión (type=decision) con side=left/right → misma capa que la decisión, línea horizontal
- Rectángulo normal (type=process/output) con side=left/right → siguiente capa, línea poligonal ortogonal (vertical → horizontal → vertical, sin diagonales)
loops (Bucle, opcional, línea discontinua)
Se usa cuando el flujo contiene lógica de «volver a un paso anterior», por ejemplo:
- Revisar después de aplicar una corrección (
apply_fix → entry) - Reintentar (
retry → checkpoint) - Iterar hasta que se cumpla una condición (
recheck → validate)
{ "from": "apply_fix", "to": "entry", "label": "Revisar tras corrección", "path": "left_edge" }
Campos:
from: id del nodo de inicio del bucle (normalmente el último paso)to: id del nodo de fin del bucle (normalmente el punto de entrada o un punto de verificación)label: etiqueta del bucle, mostrada junto a la línea discontinuapath: fijo en"left_edge"(enrutamiento por el borde izquierdo del diagrama)
Nota:
- No repitas la arista del bucle en el array
edgesentre el mismo from y to, o se renderizará duplicada. - Los nodos from/to de
loopsno participan en el cálculo de profundidad (depth).
legend
Normalmente se deja vacío [] para que el script use la leyenda por defecto de 5 colores. Si se desea personalizar:
[
{ "label": "Ejecución IA", "fill": "#E6F1FB", "stroke": "#185FA5" },
{ "label": "Salida/Informe", "fill": "#EEEDFE", "stroke": "#534AB7" },
{ "label": "Punto de decisión", "fill": "#FAEEDA", "stroke": "#854F0B" },
{ "label": "Script", "fill": "#E1F5EE", "stroke": "#0F6E56" },
{ "label": "Terminación", "fill": "#FCEBEB", "stroke": "#A32D2D" }
]
3. Ejecutar script para generar HTML
python3 <skill_dir>/scripts/flowchart.py <nodes.json> --out docs/decision-flowchart.html
El script:
- Valida unicidad de id, legalidad de side/type/role y referencias from/to
- Calcula automáticamente niveles (ramas de decisión en misma capa / bifurcaciones normales en capa inferior / punto de convergencia = max(aristas entrantes)+1)
- Calcula automáticamente x (determinado por side) e y (según nivel + altura de nodo)
- Renderiza líneas (ramas laterales horizontales / líneas poligonales ortogonales / flujo principal vertical / convergencia en tres segmentos / bucles en línea discontinua)
- Ajusta automáticamente viewBox + leyenda inferior
- Genera HTML autocontenido
Ejemplos de nodes.json
docs/halucatch-v2-nodes.json— Ejemplo completo (con bucle loop, rama triple, punto de convergencia)docs/halucatch-nodes.json— Ejemplo básicodocs/security-review-nodes.json— Ejemplo con múltiples puntos de decisióndocs/self-nodes.json— Ejemplo mínimo (9 nodos)
Lista de autoverificación
- El nodo de entrada type=entry está en la parte superior
- Cada arista tiene el campo side (bottom/left/right)
- Las aristas side=left/right de un rombo de decisión son ramas laterales (misma capa, línea horizontal)
- Las aristas side=left/right de un rectángulo normal son bifurcaciones (capa inferior, línea poligonal ortogonal)
- Un nodo, un role; los pasos mixtos ya se han dividido
- Los puntos de convergencia (múltiples aristas entrantes al mismo nodo) no requieren tratamiento especial, el script los reconoce automáticamente
- Los bucles se declaran en el campo loops, no se repiten en edges
- Todos los id de nodo en from/to de edges están referenciados (sin nodos aislados)
- Leyenda se deja vacía
[]
Preguntas frecuentes
P: ¿Qué hago si los nodos se superponen?
Verifica si falta el campo side. Las ramas de decisión deben tener side (left/right/bottom); de lo contrario, los dos nodos destino heredarían la misma posición.
P: ¿El bucle en línea discontinua no se dibuja?
El bucle se declara en el array loops (no en edges), y from/to no deben repetirse en edges. El campo path debe ser "left_edge".
P: ¿El script reporta un error de formato JSON? JSON no admite comentarios ni comillas simples. Problemas comunes: falta de coma, coma extra (al final de un array), comillas simples.
Para más preguntas, consulta docs/FAQ.md.