Explain With Diagrams

---
name: explain-with-diagrams
description: Explain processes, systems and technical designs with a diagram first, numbered steps, named actors and short plain-English supporting text. Use for how-it-works, workflow or architecture explanations; simple facts and one-step edits usually need only prose.
---

# Explain with diagrams

For a process or system explanation, lead with an appropriate diagram, followed by the few sentences needed to read it. Respect a requested text-only answer, tool, audience, detail level and output destination. This is reusable guidance, not a guarantee of agent behavior.

## Choose the right view

Determine what the user needs before drawing. A business workflow shows who does what and in what order. A backend architecture shows actual services, APIs, storage and data movement across boundaries. A sequence view shows request/response order; a state diagram shows transitions and recovery. Do not substitute a business workflow for requested backend architecture. If the request is ambiguous, infer from the supplied context or ask one focused question while collecting available evidence.

Read relevant current source and docs for an existing system. Label proposed behavior, implemented code, tested behavior and deployed status separately. A passing simulation does not prove a live integration. Verify changing technical requirements against original documentation. Do not invent queues, databases, protocols or third-party services to make a diagram look complete.

Inspect the actual pixels of a supplied visual reference before matching its style. If that is unavailable, disclose the limitation and use a clearly attributed visual brief. Match layout, spacing, shapes and annotation style while drawing only components supported by the target system.

## Make the explanation readable

Keep the main path prominent. Use numbered steps when ordering matters and name the responsible actor or service. Prefer concrete verbs and plain English; define unavoidable jargon briefly. For backend views, label arrows with the verified protocol, endpoint or data, show persistent state, and distinguish requests from responses. Keep safety, failure and recovery paths secondary but visible. Use a legend when color carries meaning.

Scale detail to the audience and task. A small workflow often fits six to eight main steps; a complex architecture may need overview plus a focused detail view. Do not force every system into the same step count. Favor readable labels and whitespace over dense text. Show assumptions and the evidence snapshot when current readiness matters.

## Produce and deliver

Prefer Excalidraw for requested editable explanatory artifacts. Use `excalidraw-diagrams` when available, or read the official format/export documentation directly. For a small in-chat explanation without a file request, Mermaid or an available inline visualization can suffice. Preserve the editable source and preview together; use the user's project artifact folder when supplied. Do not delay a requested diagram for unrelated packaging work.

Inspect rendered pixels for overlaps, clipped labels, ambiguous arrows, incorrect ordering and stale status. Include a short reading guide and source references. State the actual rendering route and any unverified parts; an editable scene plus a separately drawn PNG is not proof of an Excalidraw export. Upload, hosting and publishing follow the user's existing authorization and destination scope.

Example: "Explain the document-processing backend: show upload API, validation, persisted jobs, worker calls and status reads, then briefly explain the error path." Deliver the architecture view rather than an intake-to-completion business checklist.