Orchestrating Diagrams For Understanding

Orchestrating Diagrams for Understanding

Overview

This skill captures the diagram-selection and lightweight orchestration rules that support diagram-first-system-understanding.

This skill is a reference-layer companion to diagram-first-system-understanding, not the default user-facing entrypoint. Use it when the main skill’s embedded rules need closer inspection, refinement, or extension.

When to Use

Use this skill when:

• you are refining or reviewing the diagram-choice rules behind the main skill
• you need deeper taxonomy or sequencing rationale than the main skill should carry inline
• you want to compare alternative first-diagram strategies at the rule level
• you are evaluating whether a second diagram policy or interruption-routing rule should change

Do not use this skill when:

• the user simply wants the normal system-understanding workflow
• the main skill already has enough inline guidance for the current explanation
• the task is about Mermaid syntax rather than diagram-choice policy

Core Principles

• Diagrams serve understanding, not formality.
• Prefer a decision, not a menu.
• Use three-layer judgment: understanding problem, content object, expression granularity.
• Start with one diagram first; add a second only when needed.
• Keep stability without rigidity.
• Treat user interruptions as signals, but do not let them derail the route by default.
• Prefer the diagram that makes the key idea easiest to grasp.
• When a diagram example is shown, prefer conservative Mermaid-compatible expression over clever but fragile notation.

When making a recommendation, default to giving:

• one preferred diagram type
• one backup diagram type
• a reason for the choice
• the condition under which the backup would be better

Core Diagram Set

Keep the working set small and opinionated. First choose the diagram group that matches the dominant understanding problem, then select the specific diagram type inside that group.

Structural diagrams

Use for static organization, boundaries, grouping, layers, or dependencies.

• architecture/module relationship diagram
• layering/package grouping diagram
• dependency relationship diagram
• class diagram

Behavioral diagrams

Use for progression, interaction order, state change, or data movement through a mechanism.

• flowchart
• sequence diagram
• state diagram
• data-flow diagram

Data diagrams

Use for entities, relationships, data objects, fields, or schema shape.

• ER / data-structure relationship diagram

Runtime-environment diagrams

Use for deployment layout, node roles, runtime boundaries, or topology.

• deployment/node relationship diagram

Diagram Grouping Framework

Use the grouping framework as a fast pre-filter, not a second taxonomy pass.

• Structural: the reader first needs the static skeleton before any mechanism will make sense.
• Behavioral: the reader first needs to understand what happens, in what order, and through which interactions.
• Data: the reader first needs to understand the information model or schema shape.
• Runtime-environment: the reader first needs to understand where the system runs and how runtime nodes relate.

After picking the group, choose the narrowest diagram type in that group that makes the key idea easiest to grasp.

Selection Mechanism

Layer one: understanding problem

First identify the understanding problem. Common categories include:

• establish a system overview
• explain the main flow
• explain cross-role or cross-module collaboration
• explain state changes
• explain data organization
• explain data movement
• explain dependencies and boundaries
• explain deployment and runtime environment

Layer two: content object

Then identify the current content object. Common categories include:

• module or subsystem object
• call or interaction object
• lifecycle or state-machine object
• data-model object
• data-processing-path object
• runtime-topology object

Layer three: expression granularity

Then identify the intended granularity:

• macro
• meso
• micro

After the three-layer judgment, produce:

• preferred diagram type
• reason for preferring it
• backup diagram type
• condition where the backup is better

If no explicit user problem is present, fall back to content-object-first judgment.

Lightweight Orchestration

Default rule

Start with one primary diagram. Add a second only if the first diagram cannot cleanly solve the main understanding problem.

Signals that a second diagram is justified

A second diagram is appropriate when:

• the first diagram only explains part of the problem
• the problem naturally contains two distinct dimensions
• forcing everything into one diagram would blur the point
• the learning path naturally moves to a next layer of understanding

Common second-diagram pairings

• structural diagram → behavioral diagram when the reader needs the static skeleton first, then the main interaction or flow
• behavioral diagram → structural diagram when the mechanism is easier to grasp first, then needs component anchoring
• behavioral diagram → state diagram when a process explanation should be followed by explicit lifecycle or transition logic
• behavioral diagram → data-flow diagram when interaction order is clear but data movement still needs its own pass
• structural diagram → dependency diagram when the layout is clear but coupling or reliance patterns still need emphasis
• data diagram → behavioral diagram when the schema is clear but the reader still needs to see how the data is used
• runtime-environment diagram → behavioral diagram when deployment context is clear but runtime behavior across nodes still needs explanation

Sequencing rules

• each diagram should have one main cognitive job
• the second diagram should explicitly state what gap it fills
• prefer orthogonal complement over near-duplicate diagrams
• default to one or two diagrams; a third diagram needs stronger justification
• sequence should follow learning order, not Mermaid type order

Interruption Routing

Route user interruptions into one of three actions.

Continue the main route

Use when the interruption is a small local clarification and does not change the active understanding problem.

Insert a local diagram

Use when the interruption needs a small local diagram or local visual explanation, but the main route still makes sense.

Reassess the route

Use when the interruption changes the active understanding problem, repeatedly collides with the current diagram type’s limits, or reveals a recurring cognitive gap that suggests the route itself may be wrong.

Default rule:

• treat interruptions as local by default
• escalate to route reassessment only when they repeatedly expose the same misfit or genuinely change what now matters most

Output Contract

Whenever this skill is used, the minimum output should always include:

1. the current understanding problem
2. the current content object
3. the preferred diagram type
4. the reason for preferring it
5. one backup diagram type
6. the condition where the backup would be better
7. whether a second diagram is needed

Include these only when they apply:

1. what the second diagram should be filling in
2. which interruption-routing action applies

When showing a diagram example, default to Mermaid-safe, conservative syntax and avoid risky keywords, fragile labels, and unnecessary syntax complexity.

Common Failure Modes

• returning a list of diagram types instead of making a recommendation
• picking diagram types without stating the understanding problem
• adding second diagrams too eagerly
• switching route too quickly because of one user interruption
• refusing to switch route even after repeated evidence that the current choice is wrong
• mixing structural and behavioral concerns into one overloaded first diagram
• choosing a theoretically valid diagram that is pedagogically weak for the current question
• giving diagram advice that leads to fragile Mermaid examples
• recommending diagram forms whose example expression is too risky for stable Mermaid output

Quick Reference

| Situation | Default move | | --- | --- | | Need a first diagram | Choose from understanding problem + content object + granularity | | Several diagrams seem plausible | Recommend one preferred diagram type and one backup diagram type | | One diagram feels incomplete | Decide whether a second diagram is justified | | User asks a small local question | Use the interruption-routing test: continue the main route unless a local diagram is needed | | User repeatedly exposes the same misfit | Reassess the route |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: somra
• Source: somra/diagram-first-skills-for-claude-code
• License: MIT

Install and usage instructions live in the source repository linked above.