block-diagram

Block Diagram Skill

Use this skill when the user wants a block diagram that explains a system, model, pipeline, service, architecture, or workflow.

This is the deterministic path for architecture visuals in OpenColab. The source of truth is a D2 file, not an image-generation prompt. The default rendered style is D2 sketch mode, which gives a hand-drawn look while keeping the diagram deterministic and editable. Diagrams should stay compact, and arrows should remain unlabeled unless the label carries specific technical meaning.

Mission

Given a textual architecture description:

1. Normalize it into components, groups, and directed relationships.
2. Write a canonical diagrams/<slug>.d2 source file.
3. Render diagrams/<slug>.svg.
4. Render diagrams/<slug>.png when the user wants a raster image or when the result should be sent back to Telegram.
5. Return a short explanation of the diagram and any important assumptions.

Prerequisites

• d2 is installed and available in PATH.
• bash is available in PATH.
• The working directory is writable.

Required Inputs

• A system or architecture description.
• Optional audience: beginner, engineer, executive, paper figure, infra team, and so on.
• Optional must-include components, flows, or labels.
• Optional must-include formulas or equations.
• Optional preferred output name.
• Optional render style: sketch or clean.

If the user does not provide an audience, assume engineer. If the user does not provide an output name, derive a short slug from the system name. If the user does not provide a render style, use sketch.

Hard Requirements

• Use this skill for block diagrams instead of defaulting to a free-form image model.
• Treat the .d2 file as the canonical artifact and the rendered image as a derived artifact.
• Do not invent components, edges, protocols, or subsystems that were not implied by the request.
• Support optional formula blocks with equation: |latex only when a mathematically important transformation, loss, or objective would be materially harder to understand without an explicit equation.
• Do not generate a formula just because the request mentions math, a model, or an algorithm; include one only when the diagram would otherwise lose important meaning.
• If one ambiguity blocks a faithful diagram, ask one targeted question. Otherwise proceed autonomously.
• Keep the first diagram readable and compact. If the architecture is too dense, split it into an overview diagram plus one focused detail diagram.
• Use references/style-guide.md for layout, color semantics, naming, and grouping rules.
• Use references/patterns.md when selecting the diagram structure.
• Use ml-llm-architecture-template.md as an optional template for detailed ML, LLM, neural-network, transformer, training, or quantization architecture diagrams.
• Use references/validation.md before returning the final result.
• Use scripts/render_d2_diagram.sh to format, validate, and render the final diagram.
• Default to sketch-style rendering. Only switch to clean rendering when the user explicitly asks for a polished, paper-ready, or non-sketch output.
• Default to unlabeled arrows. Add edge labels only when they convey specific information such as a protocol, artifact, or payload that the arrow alone would not communicate.
• Never use generic edge labels such as input, output, data, result, something input, or something output.
• OpenColab normally provides OPENCOLAB_PROGRESS_FILE during provider runs. When it is set and the task is long enough to justify updates, emit bounded JSON progress events for normalization, draft completion, render start, warnings, blockers, or final artifact creation when they help the user understand real progress.
• If the rendered artifact should be sent to Telegram, emit a raw @telegram-file {"kind":"document","file":"diagrams/<slug>.svg","caption":"optional"} or @telegram-file {"kind":"photo","file":"diagrams/<slug>.png","caption":"optional"} line on its own line with no backticks or code fences. Keep the JSON on one line, use a valid kind (photo for images, never image/png/jpg), and on Windows write the path with forward slashes.
• If PNG rendering is unavailable in the current environment, fall back to the SVG artifact and send it as a Telegram document instead of pretending the PNG exists.