How Semantic Pattern Routing Works in Diagram‑Design: A Complete Technical Guide

Semantic pattern routing is the decision engine that determines what a diagram should express before deciding how to draw it, using a trigger‑based lookup table and complexity budgets to map behavioral cues to specific visual layouts.

Semantic pattern routing powers the cathrynlavery/diagram-design repository’s ability to transform abstract behavioral descriptions into concrete visualizations. Unlike traditional diagram generators that require explicit layout instructions, this system interprets semantic intent—such as "queue depth" or "policy trace"—and automatically selects the appropriate visual grammar. The mechanism operates through a structured lookup pipeline defined in skills/diagram-design/references/semantic-patterns.md and orchestrated via skills/diagram-design/SKILL.md.

The Semantic Pattern Routing Pipeline

The routing system follows a strict six‑step workflow that separates semantic understanding from rendering mechanics. Each step references specific files and line ranges within the repository.

Trigger Detection and Pattern Matching

When a user request contains behavioral cues, the skill loads the semantic‑patterns reference and scans the Routing Table for the first matching row. This lookup occurs in skills/diagram-design/references/semantic-patterns.md between lines 9–18, where triggers like "queue depth", "policy trace", or "trust boundary" are defined.

The matching process uses keyword‑based detection to identify the user's underlying intent. For example, a request mentioning "bottleneck" immediately flags the Fan‑in queue / bottleneck pattern without requiring the user to specify a diagram type.

Mapping Patterns to Visual Types

Each row in the Routing Table pairs a semantic pattern with its nearest visual type (the layout grammar). In semantic-patterns.md lines 11–12, the repository defines mappings such as:

• "Many arrivals competing for finite service capacity" → Fan‑in queue / bottleneck → Data flow visual type

This abstraction allows the system to separate meaning from representation. The pattern captures the conceptual model (competing resources), while the visual type determines the rendering engine (data flow diagram syntax).

Selection Flow in SKILL.md

The skill’s main checklist in skills/diagram-design/SKILL.md (lines 69–77) explicitly codifies the routing logic:

"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."

This conditional flow ensures that semantic routing takes precedence over generic layout selection, but provides a fallback for novel or undefined behavioral descriptions.

Budget Enforcement and Composition Rules

Every semantic pattern carries its own complexity budget specifying maximum nodes, slots, outcomes, and other constraints. According to the Composition rules in semantic-patterns.md (lines 17–23), the visual type must respect the stricter of the pattern‑budget and the type‑budget.

For instance, the Paired policy‑evaluation traces pattern might enforce:

• Maximum 2 traces
• 3–6 rules per trace
• Maximum 12 status cells total

Before rendering, skills/diagram-design/scripts/self_check.py automatically validates that the proposed diagram adheres to these constraints (referenced in SKILL.md lines 123–124), preventing visual overload and maintaining diagram clarity.

Lazy Loading and Runtime Efficiency

The architecture implements lazy loading to maintain tight memory boundaries. As documented in the "What loads when" matrix in README.md (lines 106–114), only the files necessary for the selected pattern and visual type are read at runtime.

This means semantic-patterns.md loads only when the user's request contains behavioral cues requiring semantic analysis. If the user requests a generic diagram without behavioral complexity, the system bypasses semantic routing entirely and loads only the base visual type reference (e.g., type-flowchart.md).

Practical Implementation Examples

The following examples demonstrate how to interact with the semantic pattern routing system programmatically and via CLI.

Python Routing Helper

While not part of the core repository, this illustrative helper demonstrates the lookup logic used internally:

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, pat in triggers.items():
        if re.search(rf"\b{kw}\b", request, re.I):
            # Map pattern → nearest visual type

            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 pat, type_map[pat]
    return None, None

# Example usage

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

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

CLI Usage with Pattern Selection

Using the skill from a terminal interface (Pi or Claude Code):

# Automatic routing based on semantic content

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

# Agent actions:

#   • Loads semantic-patterns.md

#   • Chooses **Secure paved road** → **Architecture** visual type

#   • Renders via assets/template.html

For advanced users, explicit pattern selection bypasses automatic trigger detection:

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

Summary

• Semantic pattern routing maps behavioral intent to visual layouts via the Routing Table in semantic-patterns.md.
• The system prioritizes pattern matching over explicit type selection, as defined in SKILL.md lines 69–77.
• Each pattern enforces a complexity budget that constrains maximum nodes and elements, validated by self_check.py.
• Lazy loading ensures semantic-patterns.md only loads for behavior‑rich requests, optimizing memory usage (documented in README.md lines 106–114).
• The final rendering plan announces the selected pattern, visual type, and budget before execution, allowing user confirmation.

Frequently Asked Questions

What triggers the semantic pattern routing system versus standard diagram generation?

The routing system activates when user requests contain behavioral, state, enforcement, or risk semantics—keywords like "queue", "policy", "trust boundary", or "bottleneck" trigger pattern lookup in semantic-patterns.md. If no semantic triggers match, the system defaults to direct visual type selection without loading the pattern reference file.

How does the complexity budget prevent diagram overload?

Each pattern in semantic-patterns.md defines hard limits on nodes, slots, and outcomes. Before rendering, the system applies the stricter of either the pattern budget or the visual type budget, then self_check.py validates the final output against these constraints. This prevents the "wall of text" effect common in automated diagram generation.

Can I force a specific semantic pattern even if my prompt doesn't contain obvious triggers?

Yes. Advanced CLI usage supports the --semantic-pattern flag to pre‑select patterns like "Compensating security layers" or "Paired policy‑evaluation traces". This bypasses the automatic trigger detection in semantic-patterns.md and immediately applies the pattern's budget and visual type mapping.

Where are the visual type definitions stored after pattern selection?

Once the routing system selects a pattern, it maps to a specific visual type reference file located in skills/diagram-design/references/. For example, a "Paired policy‑evaluation traces" pattern routes to Flowchart type, which loads type-flowchart.md (referenced in SKILL.md lines 85–92) to handle rendering syntax and layout rules.

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