How the Complexity Budget Enforces Node and Connection Limits

The complexity budget enforces hard caps of 9 nodes and 12 connections per diagram by setting boolean flags (over_node_budget and over_edge_budget) in extractor scripts that block rendering at the pre-output taste gate unless the diagram is split or detail is reduced.

The cathrynlavery/diagram-design repository implements a rigid complexity budget as a central architectural guard to guarantee diagram readability. This system prevents visual clutter by capping drawable elements and enforcing those limits at three distinct pipeline stages: extraction, validation, and rendering.

Where the Complexity Budget Is Defined

The hard numeric limits are codified in Section 7 of skills/diagram-design/SKILL.md (lines 56‑61). The specification establishes two primary constraints:

• Maximum nodes: 9 nodes per diagram
• Maximum connections: 12 edges (arrows) per diagram

Secondary limits for coral accents, lifelines, and fragments appear in lines 62‑86 of the same file, but the node and edge caps represent the primary complexity budget that gates final output.

How the Extractors Calculate Budget Flags

The extraction phase determines whether a diagram exceeds the complexity budget before any SVG generation occurs. Both the Mermaid and Draw.io extractors compute boolean flags that feed into the pre-output checklist.

Node Counting in mermaid_extract.py

In skills/diagram-design/scripts/mermaid_extract.py, the script counts drawable nodes and compares the total against the 9-node limit. Lines 1066‑1067 implement the check:

info = {
    "over_node_budget": drawable > 9,
    "over_edge_budget": len(diagram.edges) > 12,
}

When drawable exceeds 9, the script sets over_node_budget to true and emits a human-readable warning at lines 1108‑1109:

- budget: nodes OVER (max 9), edges ok (max 12)

Edge Detection in drawio_extract.py

The Draw.io extractor (skills/diagram-design/scripts/drawio_extract.py) performs an analogous calculation on the edges collection. It computes len(edges) and raises the over_edge_budget flag when the count exceeds 12. Both extractors write these flags to the digest file that downstream validators consume.

The Pre-Output Taste Gate (Section 9)

Before any diagram renders, the taste gate (defined in SKILL.md Section 9) verifies the budget flags. This mandatory checklist requires both over_node_budget and over_edge_budget to be false. If either flag is true, the pipeline aborts rendering and triggers the splitting protocol outlined in lines 87‑88 of SKILL.md.

The self_check.py script (skills/diagram-design/scripts/self_check.py) automates this validation. Running it against a generated digest exits with an error if the complexity budget is violated, ensuring no over-budget diagram reaches final output without explicit user action.

Handling Budget Overruns

When extraction detects a budget violation, the system offers two resolution paths: reducing visual detail or splitting the content across multiple diagrams.

Detail Dial Levels

The output-spec.md file (Section 11) defines a detail dial with three settings: faithful, balanced, and simplified. The faithful setting provides a conditional exemption to the 9-node limit, allowing up to 24 nodes only if the layout is zoned and the total node count stays within that expanded ceiling. All other modes enforce the strict 9-node, 12-edge cap.

Automatic Splitting Strategy

If reducing detail is insufficient, the specification mandates splitting the diagram into an overview + detail pattern. The overview diagram operates within the standard 9-node budget, while detailed sub-diagrams handle additional complexity in separate files. This approach maintains readability while accommodating complex systems.

Practical Code Examples

Running the Mermaid Extractor

Execute the extractor to generate budget flags:

python3 skills/diagram-design/scripts/mermaid_extract.py path/to/source.mmd

The output includes the budget status:

{
  "over_node_budget": true,
  "over_edge_budget": false
}

Programmatic Budget Enforcement

Automate compliance checks in custom scripts:

import json
import sys

def check_budget(digest_path):
    with open(digest_path) as f:
        data = json.load(f)
    if data["over_node_budget"] or data["over_edge_budget"]:
        sys.exit("Diagram exceeds complexity budget – split or reduce detail.")

# Usage

check_budget("diagram.digest.json")

Validating with the Self-Check Script

Run the pre-output checklist to verify budget compliance:

python3 skills/diagram-design/scripts/self_check.py generated.html

The script aborts if budget flags are violated, echoing the limits defined in SKILL.md.

Summary

• The complexity budget hard-codes limits of 9 nodes and 12 edges per diagram in SKILL.md Section 7.
• Extractor scripts (mermaid_extract.py and drawio_extract.py) calculate over_node_budget and over_edge_budget flags during the extraction phase.
• The taste gate (Section 9) blocks rendering if either budget flag is true, enforcing the limits at the pre-output stage.
• The detail dial offers a conditional exemption for faithful mode (up to 24 zoned nodes), while standard modes require strict adherence to the 9-node cap.
• Budget overruns trigger a splitting strategy (overview + detail) rather than allowing violations in single diagrams.

Frequently Asked Questions

What happens if a diagram exceeds the 9-node limit?

If a diagram exceeds 9 nodes, the extractor sets over_node_budget to true and the taste gate blocks rendering. The user must either reduce the detail level to simplified or balanced, or split the content into an overview diagram plus separate detail diagrams as specified in SKILL.md lines 87‑88.

Can the complexity budget limits be configured?

No, the limits are hard-coded in the skill definition. The 9-node and 12-edge caps appear as literal integers in mermaid_extract.py (lines 1066‑1067) and SKILL.md (lines 56‑61). The only flexibility comes from the faithful detail dial, which permits up to 24 nodes under specific zoned layout conditions defined in output-spec.md.

How does the detail dial interact with the complexity budget?

The detail dial (faithful, balanced, simplified) determines how strictly the budget applies. Balanced and simplified modes enforce the 9-node, 12-edge limits absolutely. Faithful mode allows expansion up to 24 nodes only if the layout uses zoning and the structure remains readable, providing a controlled escape valve for complex diagrams without eliminating budget enforcement entirely.

Where can I find the budget enforcement logic in the source code?

The enforcement logic spans three files: skills/diagram-design/SKILL.md defines the limits in Section 7, skills/diagram-design/scripts/mermaid_extract.py (lines 1066‑1067 and 1108‑1109) computes the flags, and skills/diagram-design/scripts/self_check.py implements the taste gate that aborts rendering when flags are true.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}