# Orchestrating Diagrams For Understanding

> Use when refining, reviewing, or extending the diagram-selection rules that support `diagram-first-system-understanding`, especially when deeper diagram taxonomy or sequencing rationale is needed than the main skill should carry inline.

- **Type:** Skill
- **Install:** `agentstack add skill-somra-diagram-first-skills-for-claude-code-orchestrating-diagrams-for-understanding`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [somra](https://agentstack.voostack.com/s/somra)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [somra](https://github.com/somra)
- **Source:** https://github.com/somra/diagram-first-skills-for-claude-code/tree/main/orchestrating-diagrams-for-understanding

## Install

```sh
agentstack add skill-somra-diagram-first-skills-for-claude-code-orchestrating-diagrams-for-understanding
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:
8. what the second diagram should be filling in
9. 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](https://github.com/somra)
- **Source:** [somra/diagram-first-skills-for-claude-code](https://github.com/somra/diagram-first-skills-for-claude-code)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-somra-diagram-first-skills-for-claude-code-orchestrating-diagrams-for-understanding
- Seller: https://agentstack.voostack.com/s/somra
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.