When to Use Semantic Pattern Routing for Diagrams: 5 Critical Scenarios

Use semantic pattern routing whenever your diagram must convey behavior, state changes, security controls, or domain-specific primitives that cannot be expressed by visual structure alone.

The cathrynlavery/diagram-design repository provides a structured approach to diagram generation that separates semantic meaning from visual representation. Understanding when to apply semantic pattern routing ensures your diagrams accurately communicate complex system behaviors rather than just static structures.

What Is Semantic Pattern Routing?

According to the source code in cathrynlavery/diagram-design, semantic pattern routing is the process of selecting a diagram's visual type based on behavioral semantics rather than just structural layout. As defined in docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md, semantic patterns represent "the axis for behavior" and never expand the visual-type taxonomy. This separation allows the system to handle complex scenarios where the meaning of a diagram depends on what the system does, not just how it looks.

The routing mechanism works by matching diagram requirements against seven defined semantic patterns in skills/diagram-design/references/semantic-patterns.md. Each pattern specifies required primitives, constraints, and maps to the nearest compatible visual type (such as Data flow, Process, or Architecture).

5 Conditions That Require Semantic Pattern Routing

1. Behavior-Driven Content

When your diagram must convey state changes, enforcement rules, risk mitigation, or policy decisions, semantic routing becomes mandatory. The skills/diagram-design/SKILL.md file explicitly states that "when behavior, state, enforcement, or risk carries the meaning, first load references/semantic-patterns.md and choose one primary pattern." Static visual types cannot capture the temporal or conditional aspects of system behavior without this semantic layer.

2. Domain-Specific Primitives

Requests requiring specialized primitives—such as queues, trust boundaries, governance catalogs, or layered security controls—trigger semantic routing. For example, the Fan-in queue / bottleneck pattern in semantic-patterns.md requires "Distinct sources; fanned ingress; an ordered queue" as primitives. These domain concepts don't map cleanly to generic visual types and require the semantic layer to identify the correct representation.

3. Complex Decision Logic

When diagrams must show rule-by-rule evaluation, divergence points, or paired policy traces, use semantic routing. The Paired policy-evaluation traces pattern handles scenarios requiring two parallel rule flows with explicit divergence markers. This pattern routes to appropriate visual types while preserving the logical structure of the decision-making process.

4. Security or Governance Focus

Any scenario highlighting trust boundaries, permitted/blocked routes, or control enforcement surfaces requires semantic pattern routing. The Secure paved road and Governance / control catalog patterns in semantic-patterns.md describe these use-cases and prescribe the nearest visual type (Architecture or Layer stack). Without semantic routing, security controls might be visually represented but semantically ambiguous.

5. Visual Ambiguity

When the meaning of a diagram would be lost or ambiguous without higher-level behavioral description, semantic routing is necessary. As noted in ADR 0002, semantic patterns exist precisely for cases where "the meaning of the diagram is lost or ambiguous without a higher-level behavioral description." If a visual-type alone cannot express the semantics, the pattern routing system bridges the gap.

The Semantic Pattern Routing Workflow

The practical workflow for applying semantic pattern routing follows four steps:

1. Load the reference: Access skills/diagram-design/references/semantic-patterns.md to review available patterns and the routing table.

2. Identify the pattern: Match your diagram requirements against the seven semantic patterns based on their selection triggers.

3. Apply constraints: Implement the pattern's budget and primitive constraints as specified in the reference documentation.

4. Select visual type: Allow the pattern to automatically select the nearest visual type (e.g., Data flow, Process, Architecture).

5. Render: Generate the diagram using the chosen visual type.

If no semantic pattern fits your requirements, you can bypass routing and select a visual type directly.

Practical Routing Examples

Below are command-line examples illustrating routing decisions using the diagram-design skill. These commands demonstrate how different semantic patterns automatically route to specific visual types.

Fan-in Queue Pattern (Bottleneck Behavior)

diagram-design import-mermaid sample-flowchart.mmd --type=data-flow --detail=balanced

This command handles the "many arrivals competing for finite service capacity" scenario. The Fan-in queue / bottleneck pattern matches this behavior and routes to the Data flow visual type, automatically selected via the --type flag.

Stage Framework Pattern

diagram-design import-mermaid sample-process.mmd --type=process --detail=balanced

When a lifecycle repeats question-input-governance-output slots across stages, the Stage framework pattern applies. This semantic pattern routes to the Process visual type to show the structured progression through defined stages.

Secure Paved Road Pattern

diagram-design import-mermaid sample-architecture.drawio --type=architecture --detail=balanced

The presence of trust boundaries and permitted/blocked routes triggers the Secure paved road pattern. This security-focused semantic pattern selects Architecture as the nearest visual type to properly convey enforcement surfaces.

Direct Visual Type Selection (No Semantic Pattern)

diagram-design import-mermaid sample-tree.mmd --type=tree --detail=balanced

Simple hierarchical structures without behavioral semantics bypass pattern routing entirely. The Tree visual type applies directly without semantic mediation.

Summary

• Use semantic pattern routing when diagrams convey behavior, state changes, or security controls rather than static structure.

• The cathrynlavery/diagram-design repository separates semantic patterns (behavior) from visual types (structure) as defined in docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md.

• Five key triggers require semantic routing: behavior-driven content, domain-specific primitives, complex decision logic, security focus, and visual ambiguity.

• The workflow loads references/semantic-patterns.md, identifies the matching pattern, applies constraints, and lets the pattern select the nearest visual type.

• Seven semantic patterns—including Fan-in queue, Secure paved road, and Paired policy-evaluation traces—map to visual types like Data flow, Architecture, and Process.

Frequently Asked Questions

What is the difference between a semantic pattern and a visual type?

Semantic patterns describe what a system does (behavior, state, enforcement), while visual types describe how information is arranged (structure, layout). According to ADR 0002 in cathrynlavery/diagram-design, semantic patterns are "the axis for behavior" and never expand the visual-type taxonomy. A single visual type like Architecture can represent multiple semantic patterns depending on the behavioral context.

How do I know if I need semantic pattern routing or can use a visual type directly?

You need semantic pattern routing if your diagram involves state changes, enforcement rules, specialized primitives like queues or trust boundaries, or complex decision logic. Check skills/diagram-design/SKILL.md: if behavior, state, or risk carries the meaning, load references/semantic-patterns.md first. For simple hierarchical or structural diagrams without behavioral semantics, select a visual type directly.

What happens if no semantic pattern matches my diagram requirements?

If none of the seven semantic patterns in references/semantic-patterns.md fit your use case, you can skip semantic routing entirely. In this case, select the appropriate visual type (Tree, Layer stack, etc.) directly using the --type flag. The semantic layer is optional when the diagram's meaning is purely structural and doesn't require behavioral context.

Where are the semantic pattern definitions stored in the repository?

The seven semantic patterns are defined in skills/diagram-design/references/semantic-patterns.md. This file contains the routing table, required primitives for each pattern (such as "Distinct sources; fanned ingress" for the Fan-in queue pattern), and mappings to nearest visual types. The overall routing logic is described in skills/diagram-design/SKILL.md, while architectural rationale appears in docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md.

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