| name | causal-loop-diagram-generator |
| description | Creates interactive causal-loop diagram (CLD) articles for MkDocs Material sites. Use when the user wants to visualize feedback loops, systems archetypes (reinforcing/balancing loops, limits to growth, tragedy of the commons), or any topic with competing runaway and stabilizing dynamics. Produces vis-network diagrams — not static images or Mermaid. |
| model | sonnet |
| license | Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) |
Causal Loop Diagram Generator
This skill produces a complete, working multi-CLD article for an MkDocs Material site. The output is a set of files that together render an article where each section discusses one feedback loop and shows it as an interactive draggable diagram, building up to a full-system view at the end.
What the user gets
When invoked on a topic (say, "make me a CLD article about supply chain bullwhip"), the skill produces:
- One JSON file per loop (
docs/sims/cld-viewer/examples/<id>-cld.json) — usually 3–5 nodes each, one per archetype loop in the topic.
- One full-system JSON combining all loops around a shared central node.
- The article markdown (
docs/articles/<slug>.md) — progressive build-up, one section per loop, with inline interactive diagrams and a fullscreen-button per diagram.
- The shared infrastructure (
docs/articles/cld-inline.js, docs/sims/cld-viewer/) if not already present in the project.
- Updated
mkdocs.yml nav entries.
Every diagram is a live vis-network instance the reader can drag, zoom, and click to inspect. Not a static image.
When to use this skill
Trigger on requests for any of:
- "Make a causal loop diagram for X"
- "Write an article about [the runaway dynamic in X]"
- "Show the feedback loops in X"
- "Add a CLD article to my site"
- A topic that has one or more reinforcing loops competing with balancing ones (AI race, virality, addiction, supply chain bullwhip, market dynamics, climate, organizational dysfunction)
If the user just wants a single quick diagram — not an article — generate just one CLD JSON and embed it inline; skip the article structure.
High-level workflow
-
Understand the system. Ask clarifying questions if the topic is ambiguous, but a single sentence is usually enough to draft a plausible loop set. List the candidate reinforcing loops (R1, R2, …) and balancing loops (B1, B2, …) before writing any JSON. Show the list to the user and confirm before generating files.
-
Verify the project layout. Determine the project root (look for mkdocs.yml). Confirm or create:
docs/articles/ (article location)docs/sims/cld-viewer/examples/ (CLD JSON location)docs/articles/cld-inline.js (inline renderer)docs/sims/cld-viewer/main.html + cld-viewer.js + the four R/B PNGs (fullscreen viewer)
-
Port missing assets. Copy the bundled assets from this skill's assets/ directory if any are missing. See the "Bundled assets" section below for the exact file map.
-
Generate one JSON per loop. Read references/json-schema.md and references/layout-templates.md. Use the 3-node triangle template for simple loops, 4-node diamond for richer ones, hub-and-spoke for the full system.
-
Write the article. Follow references/article-structure.md — frontmatter, lead, anchor example, R-loops, B-loops, status table, full system, leverage point, signals, bottom line. Required <style> and <script src="../cld-inline.js"> block at the bottom.
-
Update mkdocs.yml. Add a nav entry for the new article. If cld-viewer/index.md doesn't exist yet, add it under MicroSims.
-
Read references/pitfalls.md before changing anything in cld-inline.js, cld-viewer.js, or the rendering setup. Nine specific footguns are documented — they each cost real debugging hours to find. The most important one: never use one iframe per inline diagram; both Chrome and Firefox silently fail to render past the 5th–6th iframe on a single page, and there is no client-side workaround.
Bundled assets
Everything you need to install into a fresh project lives in assets/:
assets/
├── cld-inline.js # Inline vis-network renderer for article pages.
│ # Copy to: docs/articles/cld-inline.js
└── cld-viewer/
├── main.html # Fullscreen viewer page (used by the iframe
│ # buttons in the article). Has menu mode for
│ # sample buttons + Save/Copy positions.
├── cld-viewer.js # Fullscreen viewer's JS — loads JSON, renders
│ # network, handles drag/zoom/save.
├── reinforcing-loop-cw.png # R/B archetype icons referenced in the
├── reinforcing-loop-ccw.png # systems-thinking schema. Optional but copy
├── balancing-loop-cw.png # them through if the project will use loop
├── balancing-loop-ccw.png # iconography.
└── examples/
├── ai-flywheel-cld.json # 4-node diamond, single reinforcing loop.
├── runaway-hypothesis-cld.json # 3-node triangle, single reinforcing loop.
└── winner-takes-all-cld.json # 17 nodes, 8 loops, hub-and-spoke.
# Use as a model for full-system diagrams.
Reference docs
Loaded as needed, in roughly this order:
- references/json-schema.md — the CLD JSON format. Read first when generating loops.
- references/layout-templates.md — coordinate templates for 3-, 4-, 5-node loops and for hub-and-spoke. Read when placing nodes.
- references/article-structure.md — section-by-section template for the article markdown, including the required
<style> + <script> boilerplate. Read when writing the article.
- references/pitfalls.md — nine documented footguns with symptoms, root causes, and solutions. Read before modifying any rendering code or attempting an iframe-based design.
Default loop count
When the user gives only a topic and asks for "a CLD article," default to:
- 1 anchor example (the canonical loop everyone agrees on)
- 3–4 reinforcing loops (the runaway dynamics)
- 3–4 balancing loops (the constraints)
- 1 full-system diagram
That's 8–10 diagrams total, matching the reference Winner-Takes-All article. If the topic has fewer real dynamics, scale down — don't pad. If the user asks for "a quick diagram" or "just one loop," produce one CLD JSON and a single inline embed; skip the article scaffolding entirely.
Naming conventions
- CLD ids: lowercase, hyphenated, ending in
-cld. Example: bullwhip-amplification-cld.
- Article slug: short, hyphenated, descriptive. Example:
supply-chain-bullwhip.md.
- Loop labels:
R1: Recursive Self-Improvement, B1: Compute Constraint. Always use R<n> for reinforcing and B<n> for balancing.
What NOT to do
- Do not embed diagrams as iframes inline in the article. Use
<div class="cld-inline"> and the inline renderer. See pitfalls.md #1.
- Do not use mermaid, ASCII art, or static images for the loops. The whole point of this skill is interactive vis-network diagrams readers can drag.
- Do not soften the
border: 2px solid blue on iframes or .cld-inline divs. It's the project-wide MicroSim standard signaling interactive content. See pitfalls.md #8.
- Do not modify the global
iframe CSS rule in extra.css to "look nicer." Same reason.
- Do not skip the
<script src="../cld-inline.js"> tag at the bottom of the article. Without it, every <div class="cld-inline"> is an empty bordered box.
Confirming with the user
After you've drafted the loop list (step 1) but before generating files, show the user the proposed loop set with one-line descriptions. They almost always have an opinion on which loops to include and what to call them, and it's much cheaper to revise the list than to revise 8 JSON files.
After generating, tell the user the file paths, what mkdocs.yml changes you made, and remind them they can use the cld-viewer's "Save Positions" button to drag nodes into nicer positions and download an updated JSON.
