generador-de-diagramas

Generador de Diagramas

ACCIÓN REQUERIDA (leer y ejecutar inmediatamente)

1. AHORA: Confirma si la tarea actual está dentro del alcance de esta habilidad.
2. AHORA: Lee ../tool-index.md para verificar la disponibilidad de herramientas y rutas reales.
3. SIGUIENTE: Si faltan herramientas, llama al bootstrap; no adivines rutas.
4. ACTÚA: Entra en el primer paso del "flujo de trabajo" y ejecútalo, no te quedes en estado de confirmación.

Propósito

Crear diagramas claros y editables a partir de entradas desordenadas o estructuradas. Prefiere primero el código fuente del diagrama basado en texto para que el resultado pueda ser revisado, versionado y refinado. Renderiza a archivos solo cuando el usuario solicita una imagen/PDF o cuando un artefacto descargable sería de ayuda material.

Flujo de trabajo predeterminado

1. Identifica la intención del usuario, la audiencia y el material de origen.
2. Elige la familia de diagramas y el lenguaje usando la tabla de decisiones a continuación.
3. Normaliza entidades, relaciones, etiquetas, estados, ramas e información de tiempo/orden antes de escribir el código del diagrama.
4. Genera código fuente de diagrama conciso y legible.
5. Valida la sintaxis mentalmente y, al crear archivos, ejecuta scripts/render_diagram.py.
6. Devuelve el código fuente del diagrama más una nota breve sobre las suposiciones. Cuando se generan archivos, incluye enlaces a los archivos de salida.

No pidas demasiadas aclaraciones. Si la solicitud está poco especificada, haz suposiciones razonables y etiquétalas brevemente.

Tabla de decisiones del lenguaje de diagramas

Usa Mermaid a menos que otro lenguaje sea claramente mejor.

El usuario quiere	Preferir	Por qué
flujo de proceso, árbol de decisión, swimlane simple	diagrama de flujo Mermaid	legible y fácil de pegar en Markdown
secuencia de interacciones sistema/usuario	sequenceDiagram de Mermaid o sequence de PlantUML	Mermaid para documentación; PlantUML para formalidad UML
ciclo de vida, máquina de estados, transiciones	stateDiagram-v2 de Mermaid o state de PlantUML	sintaxis compacta de transiciones
esquema de base de datos, entidades, relaciones	erDiagram de Mermaid	notación ER portátil
modelo de clases/interfaz/objeto	classDiagram de Mermaid o class de PlantUML	Mermaid para documentación; PlantUML para UML detallado
cronograma de proyecto	gantt de Mermaid	sintaxis concisa de línea de tiempo
jerarquía, ideas, notas	mindmap de Mermaid	buen valor predeterminado para mapas de ideas
viaje del cliente/producto	journey de Mermaid	notación de viaje incorporada
historial de git	gitGraph de Mermaid	notación git incorporada
gráfico de dependencias, gráfico de paquetes, red grande	Graphviz DOT	mejores motores de diseño para gráficos densos
arquitectura con capas, clústeres, límites	diagrama de flujo Mermaid con subgráficos, clústeres Graphviz o estilo C4 de PlantUML	elegir según la fidelidad solicitada
flujo ponderado/relación tipo Sankey	sankey-beta de Mermaid cuando sea compatible, de lo contrario SVG o Graphviz	el soporte de Mermaid puede variar según el renderizador
visualización personalizada donde los lenguajes fuente no encajan bien	SVG	control preciso sobre el diseño y el estilo

Política de salida

• Siempre proporciona el código fuente editable a menos que el usuario solicite explícitamente solo una imagen.
• Por defecto, un único diagrama óptimo. Ofrece alternativas solo cuando sean genuinamente útiles.
• Prefiere sintaxis estable y simple sobre características sofisticadas que podrían no renderizarse en versiones antiguas de Mermaid/PlantUML.
• Usa etiquetas cortas. Divide el texto largo en notas fuera del diagrama cuando sea necesario.
• Evita ID de nodo ambiguos. Usa ID ASCII y etiquetas legibles.
• Conserva la terminología del usuario, pero estandariza las mayúsculas dentro de un diagrama.
• Para diagramas técnicos, incluye límites como cliente, servicio, base de datos, cola, API externa y operador/usuario cuando estén implícitos.
• Para diagramas de procesos de negocio, distingue el camino feliz, los puntos de decisión, fallos, reintentos y pasos manuales cuando estén presentes.
• Para diagramas creados a partir de texto incierto, incluye una sección de Suposiciones después del código.

Reglas de generación Mermaid

Consulta references/diagram-patterns.md para plantillas compactas.

Reglas generales de Mermaid:

• Comienza con la directiva de diagrama correcta, por ejemplo flowchart TD, sequenceDiagram, erDiagram, gantt, mindmap o journey.
• Para diagramas de flujo, usa flowchart TD a menos que el usuario solicite de izquierda a derecha; usa flowchart LR para arquitectura y pipelines.
• Usa subgráficos para swimlanes o capas de arquitectura. Nombra los subgráficos con etiquetas legibles.
• Mantén los ID de nodo estables y solo ASCII, por ejemplo ingest_service[Servicio de Ingesta].
• Pon entre comillas las etiquetas que contengan puntuación que pueda confundir al analizador.
• Usa diamantes de decisión para ramificaciones: decisión{¿Condición?}.
• Usa etiquetas de borde consistentes: -- sí -->, -- no -->, -. asíncrono .-> o == crítico ==> solo cuando tengan significado.
• En diagramas de secuencia, declara los participantes antes de los mensajes. Usa actor para humanos y participant para sistemas.
• Usa bloques alt/else/end, opt/end, loop/end y par/and/end para flujos condicionales, opcionales, repetidos y paralelos.

Reglas de generación Graphviz DOT

Usa Graphviz para diagramas de relaciones grandes, densos o sensibles al diseño.

• Prefiere digraph G para relaciones dirigidas y graph G para redes no dirigidas.
• Establece atributos de gráfico favorables al diseño al principio: rankdir=LR, nodesep, ranksep y splines=true cuando sea útil.
• Usa subgraph cluster_name para límites y subsistemas.
• Usa etiquetas simples y estilo contenido.
• Usa etiquetas de borde solo cuando añadan significado.
• Para muchos nodos, agrupa por dominio con clústeres y evita bordes de todos contra todos con muchos cruces.

Reglas de generación PlantUML

Usa PlantUML cuando el usuario solicite UML o necesite notación UML formal.

• Envuelve los diagramas con @startuml y @enduml.
• Usa los estereotipos actor, participant, database, queue, collections o component cuando sea útil.
• Usa package, rectangle o node para límites de arquitectura.
• Para diagramas de clases, incluye solo campos/métodos importantes a menos que el usuario solicite detalle exhaustivo.
• Para diagramas de actividad, usa marcadores claros de inicio/fin y etiquetas de rama explícitas.

Reglas de generación SVG

Usa SVG solo cuando los lenguajes de diagramas de texto no puedan expresar la visualización solicitada de manera confiable.

• Mantén el SVG simple, accesible y editable.
• Incluye <title> y etiquetas de texto significativas.
• Prefiere rectángulos, líneas, flechas y grupos sobre trazados complejos.
• No incrustes fuentes externas ni imágenes remotas.

Renderización de archivos

Cuando el usuario solicite PNG/SVG/PDF, crea un archivo fuente y ejecuta:

python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.mmd --format svg --out output.svg
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.dot --format png --out output.png
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.puml --format svg --out output.svg

<SKILL_ROOT> es la ruta real del directorio skills/ de este paquete; la IA debe detectarla automáticamente.

El renderizador es intencionalmente tolerante a dependencias. Intenta usar herramientas locales comunes e informa sugerencias de instalación procesables si un renderizador no está disponible. No afirmes que se renderizó una imagen a menos que el script se haya completado correctamente y el archivo de salida exista.

Lista de verificación de validación

Antes de finalizar:

• El tipo de diagrama coincide con la tarea del usuario.
• El código fuente es sintácticamente plausible para el lenguaje elegido.
• Las etiquetas son lo suficientemente cortas para caber.
• Los bordes y el orden de los mensajes reflejan la entrada con precisión.
• Las suposiciones se mencionan cuando la entrada estaba incompleta.
• Para archivos generados, la salida existe y se abre o tiene un tamaño distinto de cero.

Plantilla de respuesta común

Usa esta estructura para la mayoría de las respuestas de diagramas:

Aquí está la versión editable en [language]:

```[language]
[código fuente]

Suposiciones:

• [solo si es necesario]

Archivo renderizado: [enlace] [solo si se generó]

Para solicitudes de usuarios en inglés, responde en inglés. Para solicitudes de usuarios en chino, responde en chino a menos que pidan lo contrario.

---

## Bootstrap bajo demanda

### Límites de capacidad de automatización

| Herramienta | Instalable automáticamente | Método de instalación | Descripción |
|---|---|---|---|
| Mermaid CLI (mmdc) | ✓ | npm install -g @mermaid-js/mermaid-cli | Renderiza Mermaid a PNG/SVG |
| Graphviz (dot) | ✗ | Instalación manual | https://graphviz.org/download/ |
| PlantUML | ✗ | Requiere Java + plantuml.jar | https://plantuml.com/download |
| Python (script de renderizado) | ✓ | Ya en bootstrap | `scripts/render_diagram.py` dependencias |

### Descripción

Esta habilidad produce principalmente código fuente de diagramas en formato de texto (Mermaid/DOT/PlantUML) y no necesariamente requiere herramientas de renderizado locales. Solo se necesita el renderizador correspondiente cuando el usuario solicita explícitamente generar archivos PNG/SVG/PDF.

Si el renderizador no está disponible, `scripts/render_diagram.py` mostrará sugerencias de instalación en lugar de errores.

---

## Contexto de enrutamiento

**Entrada ascendente**: `skills/SKILL.md` (controlador principal), `routing.md`
**Condiciones de activación**: El usuario dice "dibujar", "diagrama de flujo", "diagrama de arquitectura", "diagrama de ruta de ataque", "diagrama de secuencia", "Mermaid", "Graphviz", "PlantUML"
**Salida descendente**:
- Los diagramas generados se pueden incrustar en informes de `docs-generator/`
- Los diagramas de ruta de ataque se pueden usar junto con informes de penetración de `pentest-tools/`

**Módulos relacionados del mismo nivel**: `docs-generator/` (incrustar diagramas en informes)

## Autocomprobación de finalización (DEBE pasar antes de afirmar que está completo)

- [ ] ¿Ejecuté cada paso del flujo de trabajo (no solo lo leí)?
- [ ] ¿Usé rutas de herramientas reales basadas en `tool-index`?
- [ ] ¿Produje evidencia reproducible (comandos/scripts/capturas de pantalla/informes)?
- [ ] ¿Completé y volví a escribir los elementos de la lista de verificación requeridos por RULES?