---
name: generacion-mermaid
description: >
  Generación automática de diagramas Mermaid desde planes de ejecución, workflows
  y estructuras de agentes. Convierte planes textuales en diagramas flowchart,
  sequence y state. Cargar cuando se necesite documentación visual de un plan,
  workflow o flujo de agentes en /swl:planear-fase, /swl:ejecutar-fase o docs.
version: "1.0.0"
herramientasPermitidas: [Read, Grep]
user-invocable: false
evolvable: true  # default para skill estandar
exclusiones:
  - "No cargar para diagramas de arquitectura de sistemas con componentes visuales enriquecidos (cajas con colores, leyendas, fondos oscuros) — para diagramas de arquitectura visual cargar `diagrama-arquitectura`."
  - "No cargar para diagramas de entidad-relación de base de datos — para ER cargar `dbml-experto` (DBML) o usar la sintaxis `erDiagram` de Mermaid directamente si el alcance es simple."
  - "No cargar para diagramas de arquitectura C4 en formato as-code versionable — para C4 cargar `likec4-experto`."
  - "No cargar para wireframes o mockups de interfaz de usuario — para UI prototyping cargar `wireframes-flujos`."
---
# Generación de Diagramas Mermaid

Convierte planes de ejecución, workflows y flujos de agentes en diagramas Mermaid
renderizables en Markdown. Basado en patrones de CC Workflow Studio.

## Cuándo NO cargar

- La tarea requiere diagramas de arquitectura con paleta de colores, leyendas y fondo oscuro enriquecido: cargar `diagrama-arquitectura`.
- La tarea es modelar un esquema de base de datos (ER): cargar `dbml-experto` o usar `erDiagram` directamente.
- El proyecto ya adoptó LikeC4/C4 model y el diagrama debe ser versionable as-code: cargar `likec4-experto`.
- La tarea es prototipar flujos de UI o wireframes: cargar `wireframes-flujos`.

## Cuándo cargar

- `planificador-swl` genera un plan y necesita visualización
- `documentador-swl` documenta flujos de ejecución
- `/swl:planear-fase` necesita diagrama del plan generado
- Cualquier ADR o RFC que necesite diagrama de flujo

## Tipos de diagrama soportados

### 1. Flowchart (para planes de ejecución)

```mermaid
flowchart TD
    Start([Inicio]) --> Slice1[Slice 1: API endpoints]
    Start --> Slice2[Slice 2: Frontend forms]
    Slice1 --> Test1{Tests pasan?}
    Slice2 --> Test2{Tests pasan?}
    Test1 -->|Sí| Review[Revisión de código]
    Test1 -->|No| Fix1[Corregir slice 1]
    Fix1 --> Test1
    Test2 -->|Sí| Review
    Test2 -->|No| Fix2[Corregir slice 2]
    Fix2 --> Test2
    Review --> Deploy([Deploy])
```

### 2. Sequence (para flujos de agentes)

```mermaid
sequenceDiagram
    participant U as Usuario
    participant O as Orquestador
    participant A as Arquitecto
    participant I as Implementador
    participant R as Revisor

    U->>O: Feature request
    O->>A: Diseñar arquitectura
    A-->>O: Plan aprobado
    O->>I: Implementar slice 1
    O->>I: Implementar slice 2
    I-->>O: Implementación completa
    O->>R: Revisar código
    R-->>O: Aprobado
    O-->>U: Feature lista
```

### 3. State (para ciclo de vida)

```mermaid
stateDiagram-v2
    [*] --> Discutir
    Discutir --> Planear: Contexto completo
    Planear --> Ejecutar: Plan aprobado
    Ejecutar --> Verificar: Implementación completa
    Verificar --> Ejecutar: Correcciones necesarias
    Verificar --> [*]: Verificación exitosa
```

## Patrones de conversión plan → Mermaid

### Plan con slices independientes (paralelo)

```markdown
Plan:
  Slice 1: API de usuarios (backend-api-swl)
  Slice 2: Formulario de registro (frontend-react-swl)
  Slice 3: Tests E2E (tdd-qa-swl)
  Dependencias: Slice 3 depende de Slice 1 y Slice 2
```

```mermaid
flowchart TD
    S([Inicio]) --> S1[Slice 1: API usuarios]
    S --> S2[Slice 2: Form registro]
    S1 --> S3[Slice 3: Tests E2E]
    S2 --> S3
    S3 --> E([Fin])
```

### Plan con branching (decisión)

```markdown
Plan:
  Paso 1: Analizar si el módulo existe
  Decisión: ¿Existe el módulo?
    Sí → Paso 2a: Modificar módulo existente
    No → Paso 2b: Crear módulo nuevo
  Paso 3: Tests
```

```mermaid
flowchart TD
    S([Inicio]) --> P1[Analizar módulo]
    P1 --> D{¿Existe?}
    D -->|Sí| P2a[Modificar existente]
    D -->|No| P2b[Crear nuevo]
    P2a --> P3[Tests]
    P2b --> P3
    P3 --> E([Fin])
```

### Plan con agentes específicos

```markdown
Plan:
  Fase 1: Discovery (investigador-swl)
  Fase 2: Arquitectura (arquitecto-swl) 
  Fase 3: Implementación paralela
    - backend-api-swl: API REST
    - frontend-react-swl: UI
  Fase 4: Calidad (tdd-qa-swl + revisor-codigo-swl)
```

```mermaid
flowchart TD
    S([Inicio]) --> F1[🔍 Discovery<br/>investigador-swl]
    F1 --> F2[📐 Arquitectura<br/>arquitecto-swl]
    F2 --> F3a[⚙️ API REST<br/>backend-api-swl]
    F2 --> F3b[🖥️ UI<br/>frontend-react-swl]
    F3a --> F4[✅ Calidad<br/>tdd-qa + revisor]
    F3b --> F4
    F4 --> E([Fin])
```

## Reglas de generación

### Nodos

| Tipo de paso | Forma Mermaid | Ejemplo |
|-------------|---------------|---------|
| Inicio/Fin | `([texto])` | `([Inicio])`, `([Deploy])` |
| Acción/Tarea | `[texto]` | `[Implementar API]` |
| Decisión | `{texto}` | `{¿Tests pasan?}` |
| Subproceso | `[[texto]]` | `[[Workflow anidado]]` |
| Base de datos | `[(texto)]` | `[(PostgreSQL)]` |

### Conexiones

| Tipo | Sintaxis | Cuándo |
|------|---------|--------|
| Secuencial | `-->` | Paso A antes que paso B |
| Con etiqueta | `-->|etiqueta|` | Ramas de decisión |
| Paralelo | Mismo origen, múltiples destinos | Slices independientes |
| Punteado | `-.->` | Dependencia débil/opcional |

### Estilo

- Máximo 15 nodos por diagrama (si más, dividir en sub-diagramas)
- Nombres de nodos: 3-5 palabras máximo
- Incluir agente responsable en nodos de implementación
- Usar `TD` (top-down) para planes lineales, `LR` (left-right) para pipelines
- No incluir detalles de implementación — solo flujo de alto nivel

## Integración con swl-ses

El diagrama Mermaid se incluye automáticamente en:
- `PLAN.md` generado por `/swl:planear-fase`
- ADRs en `.planning/adrs/`
- Documentación generada por `documentador-swl`
- Exports de `/swl:revisar-impacto` (blast radius visual)

## Ejemplo: conversión completa

**Input (plan textual):**
```
Feature: Sistema de notificaciones push
Slices:
  1. Modelo de datos y migraciones (backend-python-swl) — 2h
  2. API de suscripción (backend-api-swl) — 3h
  3. Worker de envío (backend-workers-swl) — 4h, depende de 1
  4. UI de preferencias (frontend-react-swl) — 3h, depende de 2
  5. Tests E2E (tdd-qa-swl) — 2h, depende de 3 y 4
Gate: Revisión de código antes de merge
```

**Output (Mermaid):**
```mermaid
flowchart TD
    S([Inicio]) --> S1[1. Modelo de datos<br/>backend-python-swl]
    S --> S2[2. API suscripción<br/>backend-api-swl]
    S1 --> S3[3. Worker envío<br/>backend-workers-swl]
    S2 --> S4[4. UI preferencias<br/>frontend-react-swl]
    S3 --> S5[5. Tests E2E<br/>tdd-qa-swl]
    S4 --> S5
    S5 --> G{Gate: Revisión}
    G -->|Aprobado| E([Merge])
    G -->|Rechazado| Fix[Correcciones]
    Fix --> S5
```

## Gotchas / Errores comunes no obvios

**Los caracteres de paréntesis `(` `)` en etiquetas de nodos rompen el render de flowchart sin error visible**: Mermaid interpreta `[nombre (acción)]` correctamente, pero `[(nombre)]` o `((nombre))` tienen significados especiales (cilindros, círculos). Si el nombre del nodo contiene paréntesis del dominio (ej: nombres de funciones), el diagrama renderiza mal o produce un nodo vacío. Causa: Mermaid usa paréntesis como operadores de forma de nodo. Fix: escapar el contenido con comillas dentro del corchete: `["nombre (acción)"]` para texto con paréntesis literales.

**Los nodos con IDs largos (más de 20 caracteres) generan conexiones que se solapan visualmente en diagramas `LR`**: Mermaid calcula el ancho de las cajas basándose en el ID del nodo en `flowchart LR`, no en el texto de la etiqueta. IDs largos crean cajas anchas que se solapan con las flechas. Causa: el layouter de Mermaid (Dagre) usa el ID para calcular el bbox inicial. Fix: usar IDs cortos (S1, P2, D3) y poner el texto descriptivo en la etiqueta: `S1[Slice 1: API de usuarios]` en lugar de `implementar-api-usuarios[Implementar API de usuarios]`.

**En diagramas `sequenceDiagram`, los mensajes con `-->>` (línea punteada) en bucles producen un loop infinito visual si el `loop` y el `end` no están correctamente indentados en el código Mermaid**: Mermaid no reporta error de sintaxis, simplemente renderiza el diagrama sin el bloque `loop`, perdiendo la semántica del flujo. Causa: el parser de `sequenceDiagram` es sensible a la indentación de las palabras clave `loop`, `alt`, `opt` y sus `end` correspondientes. Fix: usar siempre indentación de 4 espacios para el contenido de bloques `loop`/`alt`/`opt` y verificar el render en [mermaid.live](https://mermaid.live) antes de incluir en documentación.

**Los diagramas con más de 15 nodos en `flowchart TD` se renderizan con cruce de flechas inevitables porque Dagre no garantiza planarity para grafos densos**: aunque se sigan las reglas de diseño, los grafos con muchas aristas no pueden ser planares y el layout de Dagre produce cruce de aristas que confunden la lectura. Causa: el algoritmo de layout Dagre es heurístico y no garantiza planarity. Fix: dividir el diagrama en dos subdiagramas (por capa o por subsistema) con un nodo de conexión explícito entre ellos, o cambiar a `flowchart LR` que Dagre maneja mejor para grafos anchos.
