# How Semantic Pattern Routing Works in cathrynlavery/diagram-design

> Discover how semantic pattern routing in cathrynlavery/diagram-design intelligently matches user intent to visual patterns. Learn about this trigger-based lookup system that prioritizes thinking before drawing.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-08-14

---

**Semantic pattern routing matches user intent to structured visual patterns before rendering, enabling Diagram-Design to "think first, draw second" through a trigger-based lookup system.**

When you request a diagram from this skill, the system doesn't jump straight to drawing. Instead, it performs **semantic pattern routing**—a multi-step decision process that extracts the *meaning* behind your words and maps it to the most expressive visual representation. This article explains the complete routing mechanism as implemented in the `cathrynlavery/diagram-design` repository.

## What Semantic Pattern Routing Actually Does

**Semantic pattern routing** bridges the gap between natural language requests and structured diagram types. According to [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), this process activates "**when behavior, state, enforcement, or risk carries the meaning**"【SKILL.md†L69-L77】.

The workflow follows five stages:

1. **Trigger detection** — Scan user input for behavioral cues
2. **Pattern lookup** — Match against the routing table in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md)
3. **Visual type mapping** — Select the nearest layout grammar
4. **Budget enforcement** — Apply complexity constraints from both pattern and type
5. **Lazy loading** — Fetch only required reference files

## The Routing Table: Pattern-to-Visual Mapping

The core of semantic pattern routing lives in [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md). This file contains the **Routing Table** that pairs semantic patterns with their nearest visual types【semantic-patterns.md†L9-L18】.

### Example Mappings

| Trigger Phrase | Semantic Pattern | Nearest Visual Type |
|--------------|------------------|---------------------|
| "queue depth", bottleneck concerns | Fan‑in queue / bottleneck | **Data flow**【semantic‑patterns.md†L11-L12】 |
| "policy trace", rule comparison | Paired policy‑evaluation traces | **Flowchart** |
| "trust boundary", secure path | Secure paved road | **Architecture** |
| "governance catalog", controls | Governance / control catalog | **Layer stack** |

Each row encodes domain expertise: the pattern captures *what* the diagram should communicate, while the visual type determines *how* it's laid out.

## Selection Flow in the Skill

The skill's main checklist in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) makes the routing step explicit:

> *"When behavior, state, enforcement, or risk carries the meaning, first load [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) and choose one primary pattern. Then choose the nearest visual type for layout. If no pattern matches, choose the type directly."*【SKILL.md†L69-L77】

This creates a **fallback hierarchy**: semantic routing for rich behavioral requests, direct type selection for simpler structural ones.

## Complexity Budget Enforcement

Every pattern carries its own **complexity budget**—constraints on max nodes, slots, outcomes, and other structural limits【semantic‑patterns.md†L17-L23】. The rendering engine must respect the stricter of:

- The pattern's built-in budget (semantic appropriateness)
- The visual type's general budget (readability limits)

The *Composition rules* in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) specify how these budgets combine【semantic‑patterns.md†L17-L23】. Before final render, [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py) verifies compliance【SKILL.md†L123-L124】.

## Lazy Loading Architecture

Diagram-Design minimizes memory through strategic file loading. Per the README's *What loads when* matrix, [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) only loads for behavior-rich diagrams—static structural requests skip it entirely【README.md†L106-L114】.

After pattern selection, the skill loads the corresponding type reference (e.g., [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md)) for layout specifics【SKILL.md†L85-L92】.

## Practical Examples

### Terminal Invocation with Automatic Routing

```bash
/pi "Make me a diagram that shows the secure paved road for our CI/CD pipeline."

```

The agent executes semantic pattern routing:

1. Detects "secure paved road" trigger
2. Maps to **Secure paved road** pattern → **Architecture** visual type
3. Renders via [`assets/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template.html)

### Advanced: Pre-selecting a Pattern

```bash
/diagram-design:make \
   --semantic-pattern "Compensating security layers" \
   --type layer-stack \
   --size slide-16x9 \
   "Show how our WAF, IDS, and sandbox reduce risk."

```

This bypasses trigger detection, forcing the routing decision explicitly.

### Simulated Routing Logic

```python
from pathlib import Path
import re

PATTERN_TABLE = Path(
    "skills/diagram-design/references/semantic-patterns.md"
).read_text()

def route(request: str):
    """Naïve trigger detection for illustration."""
    triggers = {
        "queue": "Fan‑in queue / bottleneck",
        "policy": "Paired policy‑evaluation traces",
        "trust": "Secure paved road",
        "stage": "Stage framework with semantic slots",
    }
    type_map = {
        "Fan‑in queue / bottleneck": "Data flow",
        "Paired policy‑evaluation traces": "Flowchart",
        "Secure paved road": "Architecture",
        "Stage framework with semantic slots": "Process",
    }
    
    for kw, pattern in triggers.items():
        if re.search(rf"\b{kw}\b", request, re.I):
            return pattern, type_map[pattern]
    return None, None

print(route("Explain the bottleneck in our payment queue"))

# → ('Fan‑in queue / bottleneck', 'Data flow')

```

## Key Files in the Routing System

| File | Role |
|------|------|
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | High-level selection guide; defines when to trigger semantic routing【SKILL.md†L69-L77】 |
| [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md) | Routing table, pattern definitions, budgets, composition rules【semantic‑patterns.md†L7-L23】 |
| [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) | *What loads when* matrix showing lazy loading behavior【README.md†L106-L114】 |
| `skills/diagram-design/references/type-*.md` | Visual-type references loaded post-routing【SKILL.md†L85-L92】 |
| [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) | Budget compliance verification【SKILL.md†L123-L124】 |

## Summary

- **Semantic pattern routing** matches behavioral language to structured visual patterns before rendering
- The **Routing Table** in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) pairs triggers like "queue depth" or "policy trace" with appropriate visual types【semantic‑patterns.md†L9-L18】
- **Budget enforcement** combines pattern-specific and type-specific complexity limits【semantic‑patterns.md†L17-L23】
- **Lazy loading** keeps memory tight by only loading [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) when behavior-rich content is detected【README.md†L106-L114】
- The skill announces its routing plan (pattern, type, size, detail) before rendering for user confirmation【SKILL.md†L125-L129】

## Frequently Asked Questions

### How does Diagram-Design decide when to use semantic pattern routing?

Semantic pattern routing triggers when user requests contain behavioral cues—mentions of state, enforcement, risk, or process dynamics. According to [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), the skill checks for these signals first; absent them, it falls back to direct type selection【SKILL.md†L69-L77】.

### What happens if multiple patterns match my request?

The routing table in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) is scanned top-to-bottom, and the **first matching row wins**【semantic‑patterns.md†L9-L18】. The table ordering reflects priority: more specific behavioral patterns appear before general ones.

### Can I override the automatic pattern selection?

Yes. The skill accepts a hidden `--semantic-pattern` flag to pre-select any pattern from [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md). You can also force the visual type independently with `--type`, though the selected pattern's budget still applies.

### Where are pattern complexity budgets defined?

Each pattern's budget—limits on nodes, slots, outcomes, traces, or other structural elements—is declared in the *Composition rules* section of [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md)【semantic‑patterns.md†L17-L23】. The final diagram must satisfy both pattern and visual-type budget constraints.