When Should You Use Semantic Pattern Routing for Diagrams?

Use semantic pattern routing for diagrams whenever behavior, state changes, enforcement rules, or domain-specific primitives carry meaning that a visual type alone cannot express.

The cathrynlavery/diagram-design repository separates what a system does from how information is arranged visually. Semantic pattern routing for diagrams acts as the first decision gate in this framework, ensuring you choose the correct behavioral abstraction before selecting a layout.

What Is Semantic Pattern Routing?

Semantic pattern routing is a design process that matches diagram requests to behavioral abstractions before selecting a visual type. According to skills/diagram-design/SKILL.md, the framework requires loading references/semantic-patterns.md whenever behavior, state, enforcement, or risk carries the meaning. This routing layer prevents visual-type taxonomies from expanding beyond their structural purpose, as documented in ADR docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md.

5 Conditions That Require Semantic Pattern Routing for Diagrams

You should route a diagram through a semantic pattern first when any of the following conditions apply.

1. Behavior-Driven Content

Route through a semantic pattern when the diagram must convey state changes, enforcement rules, risk mitigation, or policy decisions. The skill guide in skills/diagram-design/SKILL.md explicitly states: "when behavior, state, enforcement, or risk carries the meaning, first load references/semantic-patterns.md and choose one primary pattern."

2. Domain-Specific Primitives

Use semantic routing when the request requires specialized primitives such as queues, trust boundaries, governance catalogs, or layered security controls. Each pattern in references/semantic-patterns.md lists required primitives. For example, the Fan-in queue / bottleneck pattern requires "Distinct sources; fanned ingress; an ordered queue."

3. Complex Decision Logic

Apply semantic pattern routing when the diagram must show rule-by-rule evaluation, divergence points, or paired policy traces. The Paired policy-evaluation traces pattern in references/semantic-patterns.md explains the need for two parallel rule flows with explicit divergence markers.

4. Security or Governance Focus

Trigger routing for any scenario highlighting trust boundaries, permitted/blocked routes, or control enforcement surfaces. The Secure paved road and Governance / control catalog patterns in references/semantic-patterns.md describe these use cases and prescribe the nearest visual type, such as Architecture or Layer stack.

5. Visual Type Alone Cannot Express the Semantics

Route semantically when the meaning of the diagram is lost or ambiguous without a higher-level behavioral description. ADR docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md clarifies that "semantic patterns never expand the visual-type taxonomy; they are the axis for behavior."

How Semantic Pattern Routing Works in Practice

The practical workflow defined in cathrynlavery/diagram-design follows a strict sequence.

1. Load the semantic-patterns reference.

2. Identify which pattern matches the request using the routing table.

3. Apply the pattern's budget and primitive constraints.

4. Let the pattern select the nearest visual type, such as Data flow, Process, or Architecture.

5. Render the diagram using the chosen visual type.

If no pattern fits, skip routing and pick a visual type directly.

Practical Command-Line Routing Examples

The following CLI snippets illustrate routing decisions using the diagram-design skill. All commands assume the skill is installed.

Fan-in Queue (Behavior Matters)

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

This command handles a request where "many arrivals compete for finite service capacity." That description matches the Fan-in queue / bottleneck pattern in references/semantic-patterns.md, which routes to the Data flow visual type via the --type flag.

Stage Framework with Semantic Slots

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

When a lifecycle repeats the same question-input-governance-output slots across stages, the Stage framework pattern applies. As documented in the semantic patterns reference, this routes to the Process visual type.

Secure Paved Road (Security Focus)

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. According to references/semantic-patterns.md, this pattern selects Architecture as the nearest visual type.

Direct Visual Type Selection (No Pattern Needed)

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

Simple hierarchical structures with no behavioral semantics bypass pattern routing entirely. The tool uses the Tree visual type directly without consulting semantic-patterns.md.

Summary

• Use semantic pattern routing for diagrams whenever behavior, state, enforcement, or risk carries the core meaning.

• The routing decision is governed by skills/diagram-design/SKILL.md and defined in references/semantic-patterns.md.

• Five primary triggers exist: behavior-driven content, domain-specific primitives, complex decision logic, security or governance focus, and insufficient visual-type semantics.

• Patterns select the nearest visual type automatically; if no pattern matches, pick a visual type directly.

Frequently Asked Questions

What file controls the semantic pattern routing decision?

The routing decision is controlled by skills/diagram-design/SKILL.md, which mandates loading references/semantic-patterns.md whenever behavioral semantics matter. ADR docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md provides the architectural rationale.

Can I skip semantic pattern routing?

Yes. If the diagram describes a simple structural relationship with no state changes, enforcement rules, or domain primitives, you can bypass routing and select a visual type directly. The Tree visual type example demonstrates this direct selection.

How do semantic patterns differ from visual types?

Semantic patterns describe what a system does, while visual types describe how information is arranged. According to ADR docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md, patterns are a separate behavioral axis that never expands the visual-type taxonomy.

Which semantic pattern handles security and trust boundaries?

The Secure paved road pattern handles trust boundaries and permitted/blocked routes, while the Governance / control catalog pattern handles control enforcement surfaces. Both are defined in references/semantic-patterns.md and route to Architecture or Layer stack visual types.

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