# How Semantic Pattern Routing Works in diagram-design: From Intent to Visualization

> Discover how semantic pattern routing translates user intent into visual diagrams. Learn its decision mechanism, pattern mapping, and layout selection in diagram design.

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

---

**Semantic pattern routing is a decision mechanism that interprets user intent through behavioral cues, maps it to predefined patterns in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), selects the nearest visual type for layout, and enforces complexity budgets before rendering.**

The diagram-design skill in the cathrynlavery/diagram-design repository uses **semantic pattern routing** to determine *what* a diagram should express before deciding *how* to draw it. This process transforms abstract user requests into concrete visual representations by matching behavioral triggers against a structured routing table and applying strict composition rules.

## The Five-Step Semantic Pattern Routing Workflow

### Step 1: Trigger Detection

When a user request contains behavioral cues—such as "queue depth", "policy trace", "trust boundary", or "stage framework"—the skill loads the **semantic-patterns reference** ([`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md)) and scans the **Routing Table** for the first matching row【semantic‑patterns.md†L9-L18】.

The system looks for specific keywords that indicate the user is describing behavior, state, enforcement, or risk rather than just asking for a specific chart type.

### Step 2: Pattern-to-Visual Type Mapping

Each row in the routing table pairs a *semantic pattern* with its *nearest visual type* (the layout grammar). For example:

- **"Many arrivals competing for finite service capacity"** → **Fan‑in queue / bottleneck** pattern → **Data flow** visual type【semantic‑patterns.md†L11-L12】
- **"Two rule traces need pass/fail/skipped/not‑reached and first divergence"** → **Paired policy‑evaluation traces** → **Flowchart** visual type
- **"Secure paved road"** → **Architecture** visual type

This mapping ensures that the visual grammar matches the conceptual meaning the user wants to communicate.

### Step 3: Selection Flow and Budget Enforcement

According to [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), the skill's main checklist explicitly states the routing step:

> *"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】

The selected pattern brings its own **complexity budget**—defined limits on max nodes, slots, outcomes, and other structural elements. The visual type must respect the stricter of the pattern-budget and the type-budget according to the *Composition rules* in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md)【semantic‑patterns.md†L17-L23】.

### Step 4: Lazy Loading of References

To maintain efficiency, only the files needed for the chosen pattern and type are read at runtime. The README includes a *"What loads when"* matrix demonstrating that [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) loads only for behavior-rich diagrams, keeping the agent's memory footprint tight【README.md†L106-L114】.

### Step 5: Final Plan Confirmation

Before rendering, the agent announces the complete plan—including the selected pattern, visual type, size, and detail level—allowing the user to confirm or adjust the approach【SKILL.md†L125-L129】.

## The Routing Table in semantic-patterns.md

The [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md) file serves as the authoritative source for routing decisions【semantic‑patterns.md†L7-L23】. This reference contains:

- **Pattern definitions** with specific trigger conditions
- **Visual type mappings** that link semantic concepts to layout grammars
- **Complexity budgets** that enforce limits on diagram size and detail
- **Composition rules** governing how patterns combine with visual types

When the agent detects a trigger, it consults this file to resolve the user's intent into a concrete rendering plan.

## Practical Implementation Examples

### Example 1: Automatic Routing via CLI

When using the skill from a terminal interface, the routing happens automatically based on your prompt:

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

```

The agent executes the routing workflow:
1. Loads [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md)
2. Matches trigger "secure paved road" → **Secure paved road** pattern
3. Maps to **Architecture** visual type
4. Renders using [`references/type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-architecture.md) and [`assets/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template.html)

### Example 2: Explicit Pattern Selection

For advanced users, the skill supports explicit pattern selection via flags:

```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 automatic trigger detection and uses the specified **Compensating security layers** pattern with the **Layer stack** visual type.

### Example 3: Python Routing Helper

While not part of the core repository, this illustrative Python code demonstrates the 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):
    # Trigger detection based on behavioral keywords

    triggers = {
        "queue": "Fan‑in queue / bottleneck",
        "stage": "Stage framework with semantic slots",
        "artifact": "Unstructured input → structured artifact",
        "policy": "Paired policy‑evaluation traces",
        "trust": "Secure paved road",
        "governance": "Governance / control catalog",
        "security": "Compensating security layers",
    }
    
    for kw, pattern in triggers.items():
        if re.search(rf"\b{kw}\b", request, re.I):
            # Pattern → visual type mapping

            type_map = {
                "Fan‑in queue / bottleneck": "Data flow",
                "Stage framework with semantic slots": "Process",
                "Unstructured input → structured artifact": "Data flow",
                "Paired policy‑evaluation traces": "Flowchart",
                "Secure paved road": "Architecture",
                "Governance / control catalog": "Layer stack",
                "Compensating security layers": "Layer stack",
            }
            return pattern, type_map[pattern]
    return None, None

# Example usage

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

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

```

## Key Files in the Routing System

| File | Role in Semantic Pattern Routing |
|------|----------------------------------|
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Contains the high-level selection guide and routing logic【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) | Defines the **Routing Table**, pattern definitions, and complexity budgets【semantic‑patterns.md†L7-L23】 |
| `skills/diagram-design/references/type-*.md` | Visual-type references (e.g., [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md)) loaded after pattern selection【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) | Validates that rendered diagrams respect the selected pattern's budget constraints【SKILL.md†L123-L124】 |
| [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) | Documents the lazy-loading architecture showing when [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) loads【README.md†L106-L114】 |

## Summary

- **Semantic pattern routing** matches user intent to predefined patterns before selecting visual representations.
- The system relies on [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) as the **Routing Table** that maps behavioral triggers to visual types.
- **Complexity budgets** from both the pattern and visual type are enforced, with the stricter limit taking precedence.
- **Lazy loading** ensures [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) and type-specific references load only when needed.
- The workflow follows: *detect intent → pick pattern → map to visual type → enforce budgets → render*.
- Users can override automatic routing using the `--semantic-pattern` flag for precise control.

## Frequently Asked Questions

### What triggers semantic pattern routing versus direct visual type selection?

According to [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), semantic pattern routing activates when the user's request involves **behavior, state, enforcement, or risk** that carries specific meaning【SKILL.md†L69-L77】. If the user simply asks for a "flowchart" or "architecture diagram" without describing behavioral semantics, the skill selects the visual type directly without consulting the semantic patterns routing table.

### How does the complexity budget system work?

Each semantic pattern defines its own **complexity budget** specifying maximum nodes, slots, and outcomes【semantic‑patterns.md†L17-L23】. When a pattern is selected, the chosen visual type must respect the stricter of either the pattern's budget or its own inherent limits. The [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) script validates compliance after rendering【SKILL.md†L123-L124】.

### Can I force a specific semantic pattern instead of using automatic detection?

Yes. The skill supports explicit pattern selection via the `--semantic-pattern` flag followed by the pattern name and the desired visual type. This is useful when you need precise control over the conceptual framing or when the automatic trigger detection might misinterpret nuanced requirements.

### What happens if no semantic pattern matches the user's request?

If the routing scan finds no matching trigger in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), the skill falls back to direct visual type selection【SKILL.md†L69-L77】. In this case, the agent chooses the appropriate diagram type (such as flowchart, architecture, or layer stack) based on the request's structure without applying pattern-specific budgets or semantics.