Mermaid.js Cynefin Syntax Guide

Mermaid.js provides dedicated syntax designed specifically to build Cynefin framework sense-making diagrams. With plain-text declarations, you can categorize tasks, incidents, and decision strategies across the five Cynefin domains without drawing complex shapes manually.

1. Core Cynefin Domain Keywords

In Cynefin syntax, items are grouped under five distinct domain blocks. Each keyword maps directly to a specific quadrant or the central area of the framework.

Domain Keyword	Cynefin Realm	Sense-Making Approach	Best Used For
`clear`	Clear / Simple	Sense → Categorize → Respond	Standard procedures, known fixes, and runbooks
`complicated`	Complicated	Sense → Analyze → Respond	Expert analysis, performance tuning, and technical reviews
`complex`	Complex	Probe → Sense → Respond	Root-cause investigation, chaos experiments, and hypothesis testing
`chaotic`	Chaotic	Act → Sense → Respond	Emergency response, rapid containment, and immediate triage
`confusion`	Aporia / Disorder	Unclear State	Uncategorized issues, unknown failure modes, or ambiguous tasks

Mermaid Edit Mermaid in VPasCode

cynefin-beta
    title Basic Decision Mapping

    complex
      "Probe system behavior"

    complicated
      "Analyze diagnostic logs"

    clear
      "Execute standard runbook"

    chaotic
      "Isolate failing cluster"

    confusion
      "Unclassified issue"

Edit Mermaid in VPasCode

2. Adding Titles & Items

Use the title keyword at the top of the diagram to set the main header. List individual items under each domain block as quoted strings ("...").

Mermaid Edit Mermaid in VPasCode

cynefin-beta
    title Incident Response

    complex
      "Investigate root cause"
      "Run chaos experiment"

    complicated
      "Analyze performance data"
      "Expert review needed"

    clear
      "Restart service"
      "Apply known fix"

    chaotic
      "Page on-call immediately"

    confusion
      "Unknown failure mode"

Edit Mermaid in VPasCode

3. Complete Practical Example

The following example demonstrates a complete software delivery & product management strategy mapped across all five Cynefin domains using Mermaid syntax.

Mermaid Edit Mermaid in VPasCode

cynefin-beta
    title Software Delivery Strategy

    complex
      "Validate product-market fit"
      "A/B test new feature variants"
      "Probe user behavior patterns"

    complicated
      "Optimize database queries"
      "Security audit & compliance review"
      "Architect microservice boundary"

    clear
      "Deploy scheduled release"
      "Update documentation"
      "Renew SSL certificates"

    chaotic
      "Mitigate active DDoS attack"
      "Failover primary database tier"

    confusion
      "Unscoped feature request"
      "Unclear legacy dependency"

Edit Mermaid in VPasCode

Conclusion

Using Mermaid’s Cynefin syntax gives agile teams, incident responders, and software architects a clean, code-driven way to categorize operational decisions. By listing actions under domain-specific keywords, you can create self-documenting sense-making frameworks directly in your technical documentation.