Diagram First System Understanding

Diagram-First System Understanding

Overview

Use this skill to guide multi-turn understanding of a codebase or technical system through diagrams as the primary explanatory medium. The goal is not to produce diagrams for their own sake, but to steadily build orientation, explain mechanisms, deepen implementation understanding, and extract design insight.

This skill is the default entrypoint for system illustration and understanding. It owns both the learning workflow and the embedded diagram-choice judgment needed when the best first diagram, the need for a second diagram, or the right response to a follow-up question is not obvious.

This skill is not a one-shot report generator. It is a continuing guidance workflow for learning systems over multiple turns.

When to Use

Use this skill when:

• the goal is to understand a codebase or technical system through diagrams
• the user wants multi-turn learning rather than a one-shot report
• the goal includes both understanding and transferable design insight
• the best starting diagram is not obvious
• more than one diagram type seems plausible
• it is unclear whether one diagram will be enough
• user follow-up may require continuing the route, inserting a local diagram, or reassessing the explanation route

When not to Use

Do not use this skill when:

• the task is only Mermaid syntax help
• the task is only a mechanical code-to-diagram conversion
• the explanation route is already trivial and does not need iterative understanding guidance
• the task is not really about system understanding

Acceptance checklist

• The skill says it is for multi-turn, diagram-first system understanding.
• The skill says diagrams are preferred when they explain structure or flow more clearly than prose.
• The skill defines the evidence priority as source code, then reference materials, then model knowledge.
• The skill requires explicit conflict handling when source and documents disagree.
• The skill defines a staged workflow from context and classification to map, focus expansion, evidence, design insight, and reassessment.
• The skill requires supplement-versus-reassessment decisions for follow-up requests.
• The skill defines a minimum per-turn output contract.
• The skill includes failure modes and a quick reference section.
• The skill treats this file as the default entrypoint rather than a companion skill.

Hard Rules

• Separate source facts, document claims, and model inference.
• Classify the object before expanding the explanation.
• Build a minimal map before diving into detail.
• Prefer diagrams when diagrams are clearer.
• In system-illustration contexts, the main diagram should default to Mermaid.
• Do not replace the main diagram with ASCII text diagrams.
• If Mermaid feels unstable, first rewrite it into a more conservative Mermaid form.
• If Mermaid still feels unstable after simplification, reduce diagram complexity rather than abandoning Mermaid.
• Start with one strong diagram before adding another.
• Prefer conservative, compatible, low-risk Mermaid expression.
• Advance one main focus per turn.
• Treat follow-up requests as diagnostic signals.
• Reassess when repeated gaps expose framing failure.
• Anchor important claims in evidence.
• Keep design commentary factual and specific.

Diagram-First Guidance

Use diagrams as the default tool for explaining:

• structure and boundaries
• module relationships
• process or call flow
• state transitions
• data movement
• extension points
• distributed coordination

In this skill, diagram-first output should default to Mermaid diagrams.

Default division of labor:

• Mermaid diagrams explain structure and mechanism
• short prose points to what matters most
• evidence anchors important claims
• code appears only as implementation proof when needed
• ASCII can exist only as tiny local support, not as the main diagram vehicle

Evidence priority:

1. source code
2. reference materials
3. model knowledge

If source code and documents disagree, explicitly identify the conflict, show the evidence on both sides, and provide the current best judgment with uncertainty if needed.

Mermaid Output Discipline

When a real diagram is warranted, the default output should be Mermaid.

ASCII may support a diagram explanation locally, but it must not become the primary diagram medium.

Structured self-check

Before outputting Mermaid, run a short internal check:

• Diagram-type fit: does this Mermaid diagram type actually match the explanation goal?
• Syntax skeleton: is the diagram head and relation structure coherent?
• Identifier safety: are node ids simple, stable, and low-risk?
• Label safety: are labels short, conservative, and unlikely to confuse the parser?
• Fragile-pattern scan: does the diagram rely on risky keywords, overloaded text, or unnecessary notation complexity?

Conservative Mermaid rules

• use simple, stable, compact ids
• keep labels short where possible
• avoid decorative punctuation overload
• avoid stuffing long natural-language sentences into nodes
• prefer common, basic, compatible relation forms
• let each diagram carry one primary cognitive job
• when a diagram becomes crowded, prefer narrowing or splitting it over clever densification

Value order:

• stable rendering > expressive cleverness > visual flourish

Fallback path

If Mermaid feels risky:

1. simplify ids, labels, and relation forms
2. remove fragile notation
3. reduce diagram scope if the Mermaid still seems unsafe
4. do not jump directly from uncertain Mermaid to ASCII main diagrams

Core recovery rule:

• simplify Mermaid rather than abandon Mermaid

Diagram Selection and Lightweight Orchestration

Use this section to stabilize the skill’s diagram choices without replacing the main learning workflow.

Core principles

• Diagrams serve understanding, not formality.
• Prefer a decision, not a menu.
• Use one strong first diagram before adding another.
• Add a second diagram only when it fills a real understanding gap.
• Keep stability without rigidity.
• Prefer the diagram that makes the key idea easiest to grasp.
• Surface orchestration reasoning only when the choice itself matters.

Diagram groups

Use the grouping framework as a fast pre-filter:

• structural: static organization, boundaries, grouping, layers, dependencies
• behavioral: progression, interaction order, state change, data movement through a mechanism
• data: entities, relationships, data objects, fields, schema shape
• runtime-environment: deployment layout, node roles, runtime boundaries, topology

Three-layer judgment

When the best diagram is not obvious, judge in this order:

1. understanding problem
2. content object
3. expression granularity

After the three-layer judgment, identify:

• one preferred diagram type
• one backup diagram type when a real alternative exists
• the condition where the backup would be better

First diagram and second diagram rules

Default to one strong first diagram.

Add a second diagram only 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 that deserves a new diagram

When a second diagram is used:

• give it one clear cognitive job
• state what gap it fills
• prefer orthogonal complement over near-duplicate restatement

Interruption routing

When a user follow-up interrupts the current explanation, route it into one of three actions. The available routes are: continue the main route, insert a local diagram, reassess the route.

Continue the main route

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

Insert a local diagram

Use when the follow-up needs a small local visual explanation, but the main route still makes sense.

Reassess the route

Use when the follow-up changes the active understanding problem, repeatedly exposes the current diagram type as a misfit, or reveals that the current framing is no longer the best way to understand the system.

Core Workflow

Stage 0: establish diagramming context

Clarify the object being studied, available materials, the immediate learning goal, and the current understanding problem.

Stage 1: classify the object and complexity

Determine object type, scale, dominant complexity sources, likely useful diagram depth, likely first diagram, and possible backup diagram.

Stage 2: produce a minimal understanding map

First explain what this is, where its boundaries are, what the main parts are, what the main line of action is, and what is most worth exploring next. Prefer the right kind of first diagram over prose when that diagram creates orientation more cleanly.

Stage 3: expand one focal point at a time

Choose one main focus for the current turn such as a request path, module collaboration, extension point, state machine, data flow, or error path. At each expansion point, decide whether to keep working through the current diagram, insert a local diagram, or introduce a second diagram that fills a justified new understanding gap.

Stage 4: anchor in implementation evidence

Support deeper explanations with concrete code locations, interfaces, configuration, protocol structures, or document evidence. Let the diagram choice itself stay grounded in what the implementation actually exposes.

Stage 5: extract design insight

Explain what problem the design solves, why it may have been chosen, what benefits it provides, what trade-offs it introduces, and which lessons transfer well. When useful, briefly explain why the chosen diagram path clarified the system.

Stage 6: accept feedback and choose supplement or reassessment

When the user asks for more, decide whether the request means continue main route, insert local diagram, or reassess route.

Adaptive Strategy

Keep the learning goals fixed, but adapt the output strategy to the object.

Consider:

• object scale: micro / medium / large
• object type: utility module / library / subsystem / framework / database / distributed system / agent system
• dominant complexity sources
• current user goal
• evidence quality
• whether the best starting diagram is obvious or ambiguous

Small objects should stay compact. Large systems should declare scope boundaries instead of pretending to fully cover everything in one pass.

Gap Handling and Reassessment

Classify follow-up requests before acting. Common categories:

• perspective gap
• granularity gap
• process gap
• evidence gap
• design-insight gap
• framing-failure signal

Operational route choices:

• continue main route when the follow-up is a small clarification
• insert local diagram when the current route still works but the gap needs a local visual explanation
• reassess route when repeated follow-ups expose the same blind spot, when the user points out a central mechanism the explanation missed, when new evidence changes the likely center of the system, or when repeated supplements still fail to make the system understandable

Output Contract

Each turn should include, as appropriate:

1. the current goal of the turn
2. one core diagram or a very small diagram set
3. concise guidance on what matters in the diagram
4. evidence anchors for important claims
5. design insight where meaningful
6. suggested next steps when useful

when the current turn needs a diagram, default to Mermaid. do not let ASCII replace a Mermaid-worthy main diagram. If Mermaid is simplified or narrowed for reliability, it should still clearly support the current understanding goal.

The following should be made explicit only when they materially help the user:

• preferred diagram type
• reason for preferring it
• backup diagram type
• condition where the backup is better
• whether a second diagram is needed
• which route now applies if a follow-up changed the explanation path

Avoid prose-heavy output, giant unreadable diagrams, code-dump explanations, false completeness, generic design praise, overuse of second diagrams, narrating the entire internal orchestration process every turn, and falling back to ASCII main diagrams because Mermaid feels uncertain.

Teaching Style

• Give orientation before depth.
• Explain why the current topic is worth looking at now.
• Let diagrams carry the main explanatory load.
• Adapt the explanation style to the system type.
• Use analogy sparingly and return to evidence.
• Treat follow-up questions as signals of the user’s learning state.
• Suggest good next steps without taking control away from the user.
• Do not over-explain internal diagram-selection reasoning when a better diagram already communicates the answer.

Common Failure Modes

• going straight into implementation detail without a map
• producing diagram-lite, prose-heavy output
• making diagrams too dense to teach with
• presenting inference as fact
• supplementing endlessly instead of reassessing
• turning the skill into diagram methodology instead of system understanding
• over-explaining internal diagram-selection reasoning
• adding second diagrams too eagerly
• keeping two parallel vocabularies for follow-up handling
• falling back to ASCII instead of emitting Mermaid
• writing Mermaid with risky or fragile syntax
• using labels or identifiers that increase parse failure risk
• overloading one Mermaid diagram until it becomes error-prone
• avoiding Mermaid entirely because of uncertainty
• discussing design quality without evidence
• ignoring the user’s current learning state

Quick Reference

| Situation | Default move | | --- | --- | | New system | Build a minimal understanding map first | | Need a first diagram | Use understanding problem + content object + granularity | | User asks for a deep detail | Attach the detail to the broader system map | | User asks a small local question | Continue the main route unless a local diagram is needed | | A follow-up reveals a local visual gap | Insert a local diagram without replacing the main route | | Mermaid feels risky | Simplify Mermaid, do not fall back to ASCII | | Repeated follow-ups hit the same blind spot | Reassess the route | | Source and docs disagree | Surface the conflict and give a reasoned judgment | | Structure or flow is hard to explain | Prefer a diagram over long prose |

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.