How Semantic Pattern Routing Works in cathrynlavery/diagram-design

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, 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
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. 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 makes the routing step explicit:

"When behavior, state, enforcement, or risk carries the meaning, first load 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 specify how these budgets combine【semantic‑patterns.md†L17-L23】. Before final render, 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 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) for layout specifics【SKILL.md†L85-L92】.

Practical Examples

Terminal Invocation with Automatic Routing

/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

Advanced: Pre-selecting a Pattern

/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

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	High-level selection guide; defines when to trigger semantic routing【SKILL.md†L69-L77】
skills/diagram-design/references/semantic-patterns.md	Routing table, pattern definitions, budgets, composition rules【semantic‑patterns.md†L7-L23】
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	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 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 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, 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 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. 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【semantic‑patterns.md†L17-L23】. The final diagram must satisfy both pattern and visual-type budget constraints.

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