# Diagram Master Prompt

Use this prompt when generating, recreating, validating, or exporting diagrams.
It is source-free and applies to architecture, workflow, state, sequence,
infrastructure, timeline, roadmap, story map, swimlane, and integration
diagrams.

## Role

You are producing a diagram artifact that must be useful to humans and safe to
handoff. Prioritize semantic correctness, readable layout, editable sources,
visual clarity, and validation evidence.

## Classify The Work

Before drawing, classify the request:

- `semantic`: explain an idea or system. Mermaid is usually acceptable.
- `inspired-by-reference`: borrow structure or style, but exact fidelity is not
  required.
- `recreation`: reproduce a source reference. Acceptance is pixel-perfect source
  fidelity unless the user explicitly accepts an approximation.

For `recreation`, inventory every visible source element before drawing:
containers, labels, icons, connectors, arrowheads, line styles, colors, borders,
spacing, rotations, z-order, and page/canvas bounds.

For source-free diagrams, create a diagram contract before drawing:

- purpose and audience;
- required nodes, groups, containers, and annotations;
- relationships and connector intent;
- expected reading flow;
- target format and validation criteria;
- known constraints or non-goals.

## Choose The Target

Use Mermaid first when the goal is semantic documentation, markdown-native
review, fast validation, or offline evidence.

Use draw.io XML or equivalent editable geometry when the goal requires exact
layout, controlled connector anchors, bend points, line jumps, rotated labels,
manual label lanes, or SVG parity.

Use a collaborative visual tool when the goal is stakeholder editing, live
review, or a team-owned visual board.

Do not treat Mermaid as a pixel-perfect recreation target when exact geometry,
icons, connector paths, rotations, or reference styling are acceptance criteria.

## Drafting Rules

- Use domain language from the task, but keep labels short enough to remain
  readable.
- Group related elements in containers only when the group adds meaning.
- Preserve clear reading flow from entry points to outcomes.
- Give repeated shapes consistent sizing, padding, typography, and spacing.
- Keep cards, groups, labels, and connector lanes visually balanced across the
  canvas.
- Avoid decorative complexity unless it supports the diagram's purpose.

## Layout And Reflow

After placing real text, subcards, chips, icons, labels, badges, and internal
connectors, run a global layout reflow before accepting the render.

For every composite container, validate actual rendered child bounds against
parent bounds. Children include text labels, nested boxes, badges, icons,
internal connectors, annotation anchors, metadata chips, and arrowheads.

If any child touches a parent edge, clips, overflows, crowds another child, or
reduces padding below the intended minimum, grow the parent container or move
children before shrinking text.

When a parent container grows, recalculate neighboring element positions,
connector routes, connector labels, annotation labels, and page/canvas bounds.
A local fix is incomplete until the whole canvas passes again.

## Text And Bounded Labels

Long text must be layout-managed. Re-evaluate wrapping, line count, width, and
placement for every note, annotation, card title, legend item, badge, pill, and
connector label.

Text inside bounded elements must fit inside its own shape. If text grows beyond
the available width, wraps poorly, overlaps another element, or visually escapes
its shape, split it into multiple lines, grow the containing shape, or move the
element.

Treat text wrapping as a geometry change. After any bounded text wraps to more
lines, recalculate the rendered bounding box and revalidate connector lanes,
neighboring labels, parent boundaries, and page bounds. The expanded box must
not cover a connector, border, arrowhead, or nearby element it previously
cleared.

Do not use label backgrounds as a visual patch. A label background must not
hide, interrupt, or visually erase the connector it describes.

## Connectors

Every connector must have an explicit source, target, semantic intent, endpoint
type, and preferred anchor side before final routing.

Connector intent determines the endpoint:

- a connector targeting a group or boundary stops at that boundary edge;
- a connector targeting a child element visibly attaches to that child;
- a connector must not drift inside a container unless the interior target is
  intentional and unambiguous.

Prefer the simplest readable connector route:

- straight when source and target have clear line-of-sight;
- one orthogonal bend when it improves readability;
- curves, multi-bend paths, diagonals, or jumps only when they avoid a real
  obstacle, crossing, or ambiguous relationship.

Before accepting a curved or multi-bend connector, verify that a straight or
orthogonal route would collide with an element, label, boundary, or reserved
lane. If no collision exists, simplify the route.

Reserve connector-label lanes after final element positions are known. A
connector label must clear the whole connector stroke, arrowhead, crossing
point, border, and adjacent labels after final wrapping and padding.

If a connector label collides with a route, evaluate fixes in this order:

1. move the label to a clear lane;
2. reroute the connector;
3. move one of the connected elements;
4. grow or reflow the containing region.

## Z-Order And Visual Integrity

Connectors and arrowheads must remain visible and must not sit hidden behind the
elements they connect. Labels must not obscure the target they describe.

Avoid connector lines crossing over containers, labels, or important symbols
whenever practical. If crossings are unavoidable, use clear spacing or line
jumps where the target format supports them.

Validate annotation target clarity: annotation arrows must visibly land on the
element or line they describe, and annotation text must not obscure the target.

## Validation Loop

Before accepting any rendered diagram, run a whole-canvas acceptance matrix:

- semantic completeness;
- text fit;
- parent containment;
- connector endpoints;
- connector route simplicity;
- connector-label clearance;
- label-to-label clearance;
- z-order and arrowhead visibility;
- whitespace balance;
- page/canvas bounds;
- editable-source/render parity when an editable source exists.

After every correction, re-render and inspect the whole canvas again. A local
fix is incomplete until no new collisions, hidden endpoints, containment
failures, or whitespace problems appear elsewhere.

A regenerated version must materially change geometry when it claims to fix a
visual finding. If the same collision, overflow, endpoint gap, or unnecessary
route persists across versions, stop re-rendering and change the layout
strategy: move elements, grow containers, reserve a different lane, or reroute
the connector.

Do not deliver the first render of a source-free diagram unless the complete
acceptance matrix passes.

## Evidence To Record

Record the following before handoff:

- target classification: `semantic`, `inspired-by-reference`, or `recreation`;
- chosen output target and reason;
- final artifact paths;
- final render pass number;
- whether text wrapping changed geometry;
- whether parent containment passed after final reflow;
- whether connector endpoints match their semantic targets;
- whether curved or multi-bend connectors have concrete obstacle reasons;
- source-vs-output gaps for recreations;
- residual visual risks, if any.

## Final Artifact Hygiene

Before final delivery, keep only:

- accepted editable source;
- accepted rendered output;
- prompt master or final prompt when it adds traceability;
- minimum QA evidence needed for review;
- short handoff note with final paths and residual risks.

Archive or exclude intermediate previews, failed renders, temporary prompts,
superseded SVGs, one-off correction notes, and source-specific prompt fragments.
Keep audit-relevant iterations in workflow evidence, an explicit archive folder,
or an ignored output location.

Do not promote source-specific text, raw user prompts, secrets, or one-off
coordinates into reusable prompt guidance. Rewrite reusable learnings as
source-free rules before adding them to the prompt bank.