Skip to content

fix(cynefin): align with Dave Snowden's framework corrections - #7922

Draft
ragelink wants to merge 1 commit into
mermaid-js:developfrom
ragelink:fix/7921-cynefin-snowden-corrections
Draft

ragelink wants to merge 1 commit into
mermaid-js:developfrom
ragelink:fix/7921-cynefin-snowden-corrections

Conversation

@ragelink

@ragelink ragelink commented Jun 28, 2026 •

Copy link
Copy Markdown
Contributor

Summary

After the Cynefin diagram (#7535) shipped, Dave Snowden — the creator of the Cynefin framework — reviewed it and pointed out three accuracy issues. This PR folds in his corrections.

For reference central domain is Aporetic not confused (that only comes in if you add liminality Clear/complicated is not a phase shift the others are. Flow does not come in from the left it is outwards from Aporetic
Thread on LI

Closes #7921. Refs #7534, #7535.

Changes

1. Central domain is Aporetic, not Confusion/Disorder

The centre is the Aporetic domain (productive not-knowing). "Confused" is a distinct concept that only appears in the liminal/dynamic version of Cynefin, which this diagram doesn't model.

  • Renamed the domain keyword confusion → aporetic and the rendered label "Confusion" → "Aporetic".
  • Renamed the theme variable confusionBg → aporeticBg across all themes.
  • The Aporetic centre no longer renders a (now meaningless) decision-model/practice subtitle.

2. Clear/Complicated is not a phase shift; the others are

The Clear/Complicated boundary is a gradient, drawn as a plain straight line, visually distinct from the wavy phase-shift boundaries (the central fold, the Complex/Chaotic boundary, and the Clear/Chaotic cliff).

3. Flow is outward from Aporetic

Added optional flow arrows radiating from the central Aporetic domain to each of the four domains, behind a new showFlow config option (default true).

Breaking change

The confusion domain keyword is renamed to aporetic. This is a breaking change to the cynefin-beta syntax, which is acceptable while the diagram is still -beta.

Test plan

  • Unit + integration tests updated and passing (cynefin.spec.ts, cynefin.integration.spec.ts)
  • New unit tests for generateGradientBoundary, the horizontal-boundary x-range, and the showFlow config default
  • Examples + multi-diagram-id-uniqueness specs passing
  • Cypress e2e updated (aporetic keyword, new showFlow: false case)
  • Docs (syntax/cynefin.md) and config schema updated; aporetic added to the spellcheck dictionary
  • pnpm build (esbuild + types) passes

With thanks to Dave Snowden for the feedback.

Folds in three accuracy corrections raised by Dave Snowden (the creator
of the Cynefin framework) after reviewing the released diagram:

- The central domain is the Aporetic domain (productive not-knowing),
  not "Confusion"/"Disorder". "Confused" only exists in the liminal
  model, which this diagram does not render. Renames the `confusion`
  keyword to `aporetic` and the `confusionBg` theme variable to
  `aporeticBg`, and drops the empty centre subtitle.
- The Clear/Complicated boundary is a gradient, not a phase shift, so it
  is now drawn as a plain straight line, distinct from the wavy
  phase-shift boundaries (the central fold, the Complex/Chaotic
  boundary, and the Clear/Chaotic cliff).
- Flow radiates outward from the Aporetic centre, not in from one side.
  Adds outward flow arrows from the centre to each domain behind a new
  `showFlow` config option (default true).

BREAKING CHANGE: the `confusion` domain keyword is renamed to
`aporetic`. Acceptable while the diagram is still `cynefin-beta`.

Closes mermaid-js#7921
@changeset-bot

changeset-bot Bot commented Jun 28, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 4b0a7b2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@netlify

netlify Bot commented Jun 28, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for mermaid-js ready!

Name Link
🔨 Latest commit 4b0a7b2
🔍 Latest deploy log https://app.netlify.com/projects/mermaid-js/deploys/6a4088d47b32b100082c5174
😎 Deploy Preview https://deploy-preview-7922--mermaid-js.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@pkg-pr-new

pkg-pr-new Bot commented Jun 28, 2026

Copy link
Copy Markdown

Open in StackBlitz

@mermaid-js/examples

npm i https://pkg.pr.new/@mermaid-js/examples@7922

mermaid

npm i https://pkg.pr.new/mermaid@7922

@mermaid-js/layout-elk

npm i https://pkg.pr.new/@mermaid-js/layout-elk@7922

@mermaid-js/layout-tidy-tree

npm i https://pkg.pr.new/@mermaid-js/layout-tidy-tree@7922

@mermaid-js/mermaid-zenuml

npm i https://pkg.pr.new/@mermaid-js/mermaid-zenuml@7922

@mermaid-js/parser

npm i https://pkg.pr.new/@mermaid-js/parser@7922

@mermaid-js/tiny

npm i https://pkg.pr.new/@mermaid-js/tiny@7922

commit: 4b0a7b2

@codecov

codecov Bot commented Jun 28, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.47%. Comparing base (f65401b) to head (4b0a7b2).
⚠️ Report is 500 commits behind head on develop.

Additional details and impacted files

Impacted file tree graph

@@             Coverage Diff             @@
##           develop    #7922      +/-   ##
===========================================
+ Coverage    77.41%   77.47%   +0.06%     
===========================================
  Files          563      563              
  Lines        74731    74777      +46     
  Branches     12614    14576    +1962     
===========================================
+ Hits         57851    57932      +81     
+ Misses       15887    15851      -36     
- Partials       993      994       +1     
Flag Coverage Δ
e2e 70.60% <97.29%> (+0.17%) ⬆️
unit 74.87% <97.53%> (+0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
packages/examples/src/examples/cynefin.ts 100.00% <ø> (ø)
.../mermaid/src/diagrams/cynefin/cynefinBoundaries.ts 100.00% <100.00%> (ø)
...es/mermaid/src/diagrams/cynefin/cynefinRenderer.ts 83.33% <100.00%> (+1.82%) ⬆️
packages/mermaid/src/diagrams/cynefin/styles.ts 100.00% <100.00%> (ø)
packages/mermaid/src/schemas/config.schema.yaml 100.00% <ø> (ø)
packages/mermaid/src/themes/theme-base.js 99.76% <100.00%> (ø)
packages/mermaid/src/themes/theme-dark.js 100.00% <100.00%> (ø)
packages/mermaid/src/themes/theme-default.js 98.26% <100.00%> (ø)
packages/mermaid/src/themes/theme-forest.js 98.13% <100.00%> (ø)
packages/mermaid/src/themes/theme-neutral.js 98.55% <100.00%> (ø)

... and 5 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@argos-ci

argos-ci Bot commented Jun 28, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build Status Details Updated (UTC)
default (Inspect) ⚠️ Changes detected (Review) 2 changed, 1 added Jun 28, 2026, 2:57 AM

@knsv

knsv commented Jun 29, 2026

Copy link
Copy Markdown
Collaborator

@ragelink Great feedback and good that yo picked this up!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Type: Bug / Error Something isn't working or is incorrect

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix(cynefin): align with Dave Snowden's corrections (Aporetic center, phase-shift boundaries, outward flow)

2 participants