# How the Complexity Budget Enforces Node and Connection Limits

> Learn how the complexity budget enforces node and connection limits with boolean flags in extractor scripts to block rendering and ensure diagram efficiency.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-15

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```python
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md).

The [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) script ([`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

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

```

The output includes the budget status:

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

```

### Programmatic Budget Enforcement

Automate compliance checks in custom scripts:

```python
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:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md).

## Summary

- The complexity budget hard-codes limits of **9 nodes and 12 edges** per diagram in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) Section 7.
- **Extractor scripts** ([`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) and [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) (lines 1066‑1067) and [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) defines the limits in Section 7, [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) (lines 1066‑1067 and 1108‑1109) computes the flags, and [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) implements the taste gate that aborts rendering when flags are `true`.