Mermaid Diagramming Engine

Generates syntactically valid, semantically precise Mermaid diagrams for discovery deliverables. Every diagram earns its place — no decorative visuals. Each diagram must compress complexity into clarity, replacing paragraphs of prose with a single visual that a reader grasps in seconds.

Principio Rector

Un diagrama que no comprime complejidad en claridad no merece existir. Cada diagrama Mermaid debe reemplazar párrafos de prosa con una visual que el lector comprende en segundos. Decoración ≠ documentación — solo diagramas que ganan su lugar sobreviven.

Filosofía de Diagramación

1. Densidad informativa. Si un diagrama no transmite más que 3 oraciones de texto, es ruido visual. Eliminar.
2. Sintaxis impecable. Un diagrama que no renderiza es peor que ningún diagrama. Validación antes de entrega.
3. Contexto > estética. Los nodos se nombran con significado de dominio, no con códigos. Las flechas llevan etiquetas. Los subgrafos agrupan con propósito.

Inputs ($ARGUMENTS)

Parameters:

• {MODO}: piloto-auto (default) | desatendido | supervisado | paso-a-paso
  • piloto-auto: Auto para selección de tipo y composición, HITL para validación de diagramas complejos (>15 nodos).
  • desatendido: Cero interrupciones. Diagramas generados automáticamente. Supuestos documentados.
  • supervisado: Autónomo con checkpoint al seleccionar tipo de diagrama.
  • paso-a-paso: Confirma tipo, composición, y validación de cada diagrama.
• {FORMATO}: markdown (default, fenced code blocks) | html (pre class="mermaid") | dual
• {VARIANTE}: ejecutiva (simplified, ≤10 nodes) | técnica (full detail, default)

When to Use

• Any discovery deliverable needs architectural, flow, or relationship visualization
• A concept is better understood visually than textually
• Cross-references between components, stakeholders, or phases need mapping
• Decision trees, timelines, or state machines need representation

When NOT to Use

• The diagram would merely repeat what the text already says clearly
• Data is better represented as a table (metrics, scores, comparisons)
• The audience won't have Mermaid rendering capability (use ASCII fallback)

S1 — Diagram Type Selection

Analyze the content and select the optimal diagram type:

Selection criteria: Choose the type that maximizes information density while minimizing cognitive load.

S2 — Diagram Composition Rules

1. Syntax validity: Every diagram MUST render without errors in standard Mermaid renderers (GitHub, GitLab, Obsidian, Mermaid Live Editor).
2. Node naming: Use descriptive IDs (authService not A1). Wrap display labels in quotes if they contain spaces.
3. Edge labels: Every relationship/arrow carries a label explaining the connection.
4. Subgraphs: Group related nodes. Name subgraphs meaningfully.
5. Direction: Use TD (top-down) for hierarchies, LR (left-right) for flows/sequences.
6. Color/styling: Use classDef for semantic coloring (e.g., classDef critical fill:#f96,stroke:#333). Max 4 style classes per diagram.
7. Size discipline: Max 20 nodes per diagram. If more needed, split into multiple diagrams with cross-references.
8. Accessibility: Include a 1-line text summary before each diagram for screen readers and non-rendering contexts.

S3 — Deliverable-Specific Diagram Catalog

Each discovery deliverable has recommended diagram types:

Minimum: 1 diagram per deliverable. Recommended: 2. Maximum: 4 (avoid visual overload).

S4 — Quality Validation

Every diagram passes through validation:

S5 — Output Format Integration

In Markdown deliverables (default):

> **Figure N**: [1-line description for accessibility]

```mermaid
[diagram code]
```

*Source: [CÓDIGO] / [DOC] / [INFERENCIA]*

In HTML deliverables (on demand): Embed Mermaid via <pre class="mermaid"> tag with Mermaid JS CDN include. Add alt attribute with text description.

Trade-off Matrix

Assumptions

• Target renderers support Mermaid v10+ syntax
• Readers have basic familiarity with flowchart/diagram conventions
• Diagrams supplement text, never replace it entirely

Limits

• Cannot generate raster images (PNG/SVG) — output is Mermaid code only
• C4 diagrams use Mermaid's C4 extension (may not render in all contexts)
• Complex diagrams (>20 nodes) require decomposition into sub-diagrams
• Animation/interactivity not supported in Mermaid

Edge Cases

• If source data is insufficient for a meaningful diagram → skip diagram, note gap
• If two diagram types are equally valid → prefer the one with fewer nodes
• If diagram would contain sensitive data (credentials, internal IPs) → abstract to categories

Validation Gate

Before delivering any diagram:

1. Paste into Mermaid Live Editor mentally — would it render? Fix syntax if not.
2. Does it add information the text doesn't? If no, remove it.
3. Can the target audience understand it without explanation? If no, simplify.
4. Are all labels/names consistent with the document? If no, align.

Casos Borde

Decisiones y Trade-offs

Knowledge Graph

graph TD
    subgraph Core["Mermaid Diagramming Engine"]
        A["Type Selection"] --> B["Composition Rules"]
        B --> C["Syntax Validation"]
        C --> D["Quality Validation"]
    end
    subgraph Inputs["Inputs"]
        E["Source Content"] --> A
        F["Diagram Type Hint"] --> A
        G["Audience Level"] --> B
    end
    subgraph Outputs["Outputs"]
        D --> H["Mermaid Code Blocks"]
        D --> I["Accessibility Text"]
    end
    subgraph Related["Related Skills"]
        J["data-viz-storytelling"] -.-> A
        K["output-engineering"] -.-> H
    end

Output Templates

Markdown (default)

• Filename: embedded within parent deliverable (e.g., 03_Analisis_ASIS_{cliente}_{WIP}.md)
• Structure: Figure number > accessibility text summary > fenced mermaid code block > source evidence tag

HTML

• Filename: embedded within parent HTML deliverable
• Structure: <pre class="mermaid"> with CDN v10; alt attribute with accessibility text; responsive container; print fallback CSS

DOCX (bajo demanda)

• Filename: {fase}_{entregable}_{cliente}_{WIP}.docx
• Generado via python-docx con MetodologIA Design System v5. Portada con logo y metadatos, TOC automatico, headers/footers con nombre del skill y numeracion, tablas zebra, titulos Poppins navy, cuerpo Montserrat, acentos gold. Diagramas Mermaid exportados como imagen PNG e incrustados en el documento.

XLSX (bajo demanda)

• Filename: {fase}_{entregable}_{cliente}_{WIP}.xlsx
• Generado con openpyxl bajo MetodologIA Design System v5. Headers con fondo navy y tipografía Poppins blanca, formato condicional, auto-filtros activados, valores sin fórmulas. Hojas: Diagram Catalog (tipo, entregable, nodos, descripción), Validation Gate por diagrama, Deliverable-Diagram Matrix.

PPTX (bajo demanda)

• Filename: {fase}_{entregable}_{cliente}_{WIP}.pptx
• Generado via python-pptx con MetodologIA Design System v5. Slide master navy gradient, titulos Poppins, cuerpo Montserrat, acentos gold. Max 20 slides variante ejecutiva / 30 variante tecnica. Speaker notes con referencias de evidencia [DOC]/[INFERENCIA]/[SUPUESTO].

Evaluacion

Umbral minimo: 7/10 en cada dimension para considerar el skill production-ready.

Cross-References

• discovery-orchestrator — coordinates which diagrams each deliverable needs
• All pipeline skills — embed diagrams in their output artifacts
• brand-html / brand-html-extended — HTML embedding with Mermaid JS

Output Format Protocol

Default output is Markdown with embedded Mermaid diagrams. HTML generation requires explicit {FORMATO}=html parameter.

Output Artifact

Primary: Mermaid diagram code blocks ready to embed in Markdown or HTML deliverables. Each diagram includes accessibility text summary, source evidence tag, and figure numbering.

Supported diagram types: C4Context, C4Container, flowchart, sequenceDiagram, erDiagram, stateDiagram-v2, gantt, mindmap, quadrantChart, classDiagram, gitGraph, journey.

Autor: Javier Montaño | Última actualización: 12 de marzo de 2026