/miro-code-explain-on-board

name: miro-code-explain-on-board
description: Use when the user wants to explain or visualize a codebase on a Miro board — produces a minimal, notation-correct set of architecture / structure / behavior diagrams (flowchart, UML class, UML sequence, ERD) plus a short companion document, grounded in real repo artifacts.

Explain a Codebase on a Miro Board

You are a senior software engineer and visual architect. Produce high-quality, readable visual explanations of a codebase for engineering + product audiences on a Miro board.

Artifacts are composed as a canvas SVG and written to the board with the Miro MCP canvas tools. Diagrams are **Mermaid** bodies inside `<foreignObject data-type="diagram">` widgets; the companion document is a `<foreignObject data-type="doc">` widget. This skill owns *what* to draw; the canvas tools own *how* the SVG is written — never restate their mechanics from memory, load them (step 5).

**Artifact-first:** cite repo symbols (files / modules / types) only when known. Do NOT invent. If something cannot be grounded, mark it `UNKNOWN/VERIFY` in notes rather than guessing.

0. Inputs

1. **Board URL.** If missing, ask. Required to place artifacts. To target a specific frame, the URL may include `?moveToWidget=<frame_id>` — the composition then lands inside that frame with frame-relative coordinates. 2. **What to explain.** A repo, subsystem, or specific question. If unclear, ask for scope before analyzing.

Core diagramming principles

Apply these throughout. The full ruleset (R1–R9 notation/edge rules, H1–H4 budgets) lives in `references/diagramming-principles.md` — **read it before drafting.** The essentials:

• **Separate views, one question per diagram (R1/R2).** Never mix abstraction levels in one diagram: system context, runtime architecture, module decomposition, static structure, runtime behavior, algorithms, UX flow are distinct. Split when dense.
• **Notation must match semantics (R3).** UML class = real code types with members. UML sequence = one concrete time-ordered scenario. ERD = persistent entities/tables. Flowchart = universal fallback for architecture / modules / processes when the others don't fit.
• **Typed edges only (R4/R8).** Banned generic labels: *uses, contains, relates, has, supports, manages, integrates*. Prefer typed verbs: calls, invokes, reads, writes, queries, persists, publishes, subscribes, enqueues, HTTP/REST/gRPC, imports types, configures, initializes. If you can't ground the relation, label it `UNKNOWN` + add a verify note.
• **No inventories, no duplication, truthfulness over completeness (R4/R5/R6).** Every diagram adds unique value and answers a real question.
• **5-second scan (H1).** ~10–15 nodes per diagram (split at >15, MUST split at >20). Target ~4–6 diagrams total. Sequence: ~5–8 lifelines, ~12–20 messages. Class: ~3–5 high-signal members each. ERD overview: PK/FK/UQ + 2–4 distinguishing fields, note omissions.

Workflow

1. Analyze the repo — extract candidate views (no rendering yet)

Identify, as available:

• **Runtime units:** apps / services / jobs / workers, datastores, external systems
• **Code structure:** modules / packages / bounded contexts
• **Domain model:** key entities / types
• **Behaviors:** request lifecycles, pipelines, events, background jobs
• **Algorithms:** localized control flow worth visualizing

Keep candidate views separate (R1).

2. Design the minimal diagram set (PLAN) — announce it in chat

Produce a diagram plan and state it before creating anything, so the user can redirect. For each diagram:

• **id** (D1, D2, …) and **title**
• **audience** (eng / product / both)
• **question it answers** (explicit, one question)
• **scope:** included / excluded
• **notation:** flowchart / uml_class / uml_sequence / entity_relationship
• **edge semantics** (one line — required for flowchart): e.g. "compile-time dependencies", "runtime calls", "data reads/writes"
• **key elements** that must appear
• optionally 1–3 **code anchors** (file/module/function) for human navigation

Keep it the minimal set that conveys core understanding (R2/R5); prefer several small diagrams over one mega-diagram (R7).

Get the plan right here: a diagram widget cannot be moved or deleted through the canvas tools once created, so a discarded diagram stays on the board.

3. Draft each diagram (notation-bound, format-free)

Draft content consistent with the chosen notation's semantics, using typed edges. Add `UNKNOWN/VERIFY` notes where needed. Do not write Mermaid yet.

4. Pre-compilation checks (MANDATORY, before writing any Mermaid)

• **Split check:** any draft >15 elements → split into "Overview" + "Deep dive"; >20 → MUST split.
• **Edge-label check:** scan for banned verbs (uses/contains/relates/has/supports/manages/integrates) → replace with typed verbs or `UNKNOWN`.
• **Import-graph check (R9):** if a flowchart is a module/import dependency graph, prefer **unlabeled** edges + a one-line legend note ("`-->` = compile-time dependency"); keep labels only where they add object-level meaning ("imports types", "imports UI components"). Containment is a cluster/subgraph or note — never a "contains" edge.
• **Flowchart shape hygiene (architecture/system/module fallback) — MUST:** use **only plain rectangle nodes** `id[Label]`. Do NOT use decision diamonds `{ }`, stadium/terminator `( )`, subroutine `[[ ]]`, cylinder/database `[( )]`, or other special Mermaid shapes. Special shapes are allowed **only** when the diagram is a true algorithm / control-flow view (the R1 "Algorithms" case). This overrides the shape variety shown in the loaded diagramming guidance's worked example.
• **ERD overview check:** trim to PK/FK/UQ + 2–4 distinguishing fields and add an omission note, unless the user explicitly asked for the full schema (then make a separate "ERD Deep Dive").

5. Load the canvas guidance

Before composing anything, load two pieces of guidance from the Miro MCP server: first the canvas