ea-diagram-composition

Logic: AI + AI Power Tools checks. The AI chooses the layout and judges the result; deterministic code computes geometry and places it; rule-based code checks it.

What it is for

Use it to draw a diagram from model content that follows your notation's conventions, or to make an existing one read as deliberate. You end with a diagram in EA that has been rendered, checked and corrected, within a fixed number of passes.

A diagram is not a picture of a model. It is an argument about the model, made visually, and it works when a reader can follow the argument without being told how. ea-diagram-composition is the skill for the part a model cannot tell you: where things go.

It builds a diagram from model content instead of hand-placing elements. The method is a loop:

It is language-neutral. The engine knows nothing about ArchiMate or BPMN. Each notation's conventions (box sizes, spacing, title style, connector routing, standard views, which visual channels are already spoken for) are read from a data file called a binding. Eleven notations ship with a binding; see Notation bindings. The deterministic parts are described in depth in Layout grammars, Composition modules, Notation bindings and Verification modules.

The skill's central rule: never hand a diagram to someone without looking at it. Generating geometry and trusting it is how overlapping boxes and clipped labels ship.

Capabilities it uses

When to use it, and when not

Use it when building a diagram from model content rather than hand-placing elements, when a generated diagram looks untidy and you need to know why, when producing a detail, review or executive version of one model, or when reproducing a diagram from a reference picture.

How it works

Step 0. Resolve the language binding. (engine, rule-based) Before choosing anything, the AI asks whether the notation's conventions are already recorded. The binding resolver loads the bindings for the technologies the repository has (once per repository) and decides which diagram type's conventions apply to one diagram (once per diagram). It is given both the diagram's stored style and its diagram type, because about half of real diagrams carry no MDG type in the style and identify themselves by diagram type alone. For a diagram about to be created, the AI states what it will be created as.

Every answer carries a path, a confidence and a reason:

An unbound or ambiguous answer is a finding to report, not a gap to paper over. The AI quotes the reason and says what it did instead: compose with the engine's defaults for "unbound"; choose one candidate explicitly, or use the defaults, for "ambiguous". It never takes the first candidate and never reaches for a binding the resolver declined. For "not installed", it checks the id against the installed inventory, because ids carry their own version and are not guessable. A weak confidence is reported beside the result.

A direct lookup of one binding by technology id also exists, but it checks nothing against what the repository has installed and returns nothing silently when there is none, so it is not used to pick a binding for a diagram.

Can this diagram be produced, and who places it? Four properties of the resolved diagram type answer in a fixed order:

• Not producible: the AI says so and stops. It does not compose the nearest shape it does have. This covers the diagram types EA lays out itself, such as a UML sequence or timing diagram.
• Producible and composed: continue at step 2.
• Producible, not composed (graph): skip step 2. Create the elements, ask EA to lay them out with the spacing from the binding, then style and verify.

A viewpoint can override its diagram type's grammar and carries the same four properties. The diagram type also supplies box size and spacing, connector routing, which visual channels are free, whether to draw a title, and which standard view fits the content. Composing against another notation's binding is worse than composing against none.

Step 1. Choose a grammar. AI Analysis of 147 professionally drawn reference diagrams found their variety resolves into a handful of layout grammars, not 147 special cases. Picking the right one is most of the quality. When step 0 found a binding, the grammar is already chosen: the binding states it for each diagram type. Otherwise the AI chooses from the shape of the content. The core choices:

Four further composed grammars (matrix, radial tree, chevron stack and treemap) are available to bindings and callers. Layout grammars describes all eleven.

If none fits, the AI says so and uses graph. A forced grammar reads worse than an honest one. A capability model in swimlanes is not a swimlane diagram; it is a capability model that has been made harder to read. The exception: an EA-semantic type must never be laid out as a free graph. A sequence diagram handed to a graph layout places the participants and ignores the message order, which looks like a sequence diagram and is not one. The AI says it is classified and not producible, and stops.

Step 2. Compute the geometry. (engine, with a question for you when needed) Only where the engine composes the geometry. Plain data goes in (bands or lanes of named items carrying their EA element ids) and positions come out.

• Element ids are preserved exactly. Every item comes back with its left, top, right and bottom in EA's convention, plus its container and index; every container carries its own rectangle and a label rectangle.
• EA's vertical axis is inverted: top and bottom are negative, and top is the larger number, so height is top minus bottom. Getting this backwards silently flips every vertical decision. The engine handles it.
• Where a binding exists, the spacing and sizes come from it rather than from numbers written by hand: a binding's figures were measured from real diagrams. An unknown setting is refused rather than ignored.
• The AI passes the item names when it asks for the spec. A binding's box is measured for a typical name. EA does not clip a name it cannot fit: it grows the drawn box and leaves the stored geometry alone. Measured live, a 36-character name with no space in it was drawn 169 pixels wide against a stored 60. With the names, the width is widened before the engine sees it, the same width for every peer. What has to fit is the longest space-free run, because EA wraps on spaces only. Without the names, nothing is measured.
• Per-concept sizes are the caller's to apply; the spec carries the default size only.

When the width and the content conflict, you decide. A width stated on purpose and content wider than it are both facts, and there are two legitimate drawings: extend the box, or keep the width and let the text overlap the border. Which one a diagram wants is not the AI's call. The spec and the composition report the conflict, and the report carries the question ready to put to you. Your answer is "widen" or "overlap"; if nobody answers, widening is applied because it is the safe direction (the stored geometry then equals what EA paints), and an unanswered conflict is a question the AI still owes you. Layered bands report the same way when an explicit minimum band width is narrower than the bands' contents. Each conflict records where it is, what drives it, the requested and required widths, the two options with their effects, which was applied, whether it was answered, and the question.

Step 3. Place and style. (AI Power Tools operations, AI choices) Place with add_elements_to_diagram_bulk, passing explicit coordinates for every element and no layout. A named layout style would discard every coordinate just computed. Then style, in this order:

1. Elements: set_diagram_object_appearance, or the bulk form for a palette. Colors are "#RRGGBB" or a name.
2. Connectors: add_connectors_to_diagram_bulk first, then set_diagram_link or set_diagram_links_bulk for route, color and width.

A connector needs a stored link before it can be styled. EA draws the relationship between two placed elements whether or not a stored link exists, so a visible line is not evidence it can be styled. A link reported with no stored identity has nothing to write to; it is added to the link layer first, otherwise the style call reports that the link is not stored.

Appearance scope. set_diagram_object_appearance changes one placement on one diagram; set_element_appearance changes the element on every diagram. The skill reaches for the first. Changing the second to fix one view surprises whoever looks at another.

The judgment the scripts cannot encode AI:

• Each notation already claims some visual channels. ArchiMate's layer colors are spoken for; recoloring by lifecycle destroys the notation while looking like a feature. The AI asks which channels the notation claims and which are free; if fill is taken, it uses border, opacity or an icon.
• One variable per channel. Fill is lifecycle or ownership, never both.
• Uniform sizing within a role is not cosmetic. Varying size reads as varying importance.
• Empty space is structure; a consistent gutter between bands says the bands are peers.
• Fewer connectors is usually better. A diagram showing every relationship shows none. The AI says what was left out.

Step 4. Verify. AI Power Tools verify_diagram reloads the diagram unconditionally, renders it, and returns the image with the full placed geometry (rectangles, stacking order, decoded connector routing and color, canvas extents). The reload is why it exists: EA caches renders per diagram, so rendering after an out-of-band write can return a stale image that looks plausible. It has no way to skip the reload. The AI uses it, not get_diagram_png, when the question is "is this right". To check what color EA actually drew, it asks for the SVG and reads the stroke and fill from the markup. A color property read back proves nothing, because EA echoes whatever was written. To see the diagram as EA itself shows it, the AI also looks at EA's window AI with computer use; otherwise you.

Step 5. Check and correct. (engine checks, AI corrects) The diagram check reads a verify_diagram result and nothing else. The groupings are the AI's job to supply, not the checker's: which elements play one role, sit in one row or column, form a stack or ring around a hub are composition facts that coordinates cannot reveal.

A rule with no grouping does not run. The report lists any grouping that was declared but could not be judged, and the text rules need the SVG. Three metrics always appear with a denominator beside them (how many roles were measured, how many spacing groups, whether a title convention was stated); a zero denominator means nothing was measured. The AI reads findings of all severities, not only errors. "Clean" means no errors, not "nothing found", and not "this diagram reads well". The full catalog is in Verification modules.

The loop is bounded: three correction passes, then report what is left. A stall test catches a pass that altered nothing; the AI stops at the first stall. If it is still wrong after three passes, the grammar was the wrong choice, not the spacing; the AI says so and says what it tried. If a diagram cannot be made to work ("twenty-eight elements with sixty connectors will not read at this size"), it says why and proposes a split or an executive view.

Presentation profiles: detail, review, executive

A presentation profile says how much detail a view shows, independent of the diagram type. The same content can be duplicated into a second diagram under a different profile, giving a live detail view and a live executive view of one model, not a screenshot of one of them. Three bindings ship profiles: ArchiMate 3, BPMN 2.0 and the UML base notation. Their settings are identical; the descriptions differ.

The profile states what it shows; EA is told what to hide. The seven display settings are hiding connector labels, element stereotypes and connector stereotypes, attribute types, operation return types and operation brackets, and showing element notes, each verified by rendering through set_diagram_display. The one setting whose sense does not flip is notes, which EA hides by default.

• "None" for compartments does not remove a compartment. EA's display settings reduce a compartment's detail to names (balance rather than balance: Decimal) and do not remove it. The AI says "names only" rather than implying a class has no members.
• The executive profile collapses parallel connectors. Collapsing hides relationships, so the diagram must carry an annotation saying what was summarized. collapse_parallel_connectors is a dry run by default, refuses when directions disagree, and always returns annotation text that must be placed. expand_parallel_connectors reverses it. The checker raises an error if the annotation is missing.
• The checker is told the profile so it does not report what the view hides on purpose. A profile never suppresses a structural defect; overlaps are wrong under every profile. Suppressed rules are listed on the report.
• Notation caveats stated in the bindings: an executive BPMN view loses the gateway conditions, so it is a summary of the happy path and must be called that; an executive UML view shows class names only.

What you get

• A diagram built from your model content with every element at a computed position, styled within the notation's conventions.
• A statement of which binding applied and how confidently, and what was done where it was unbound or ambiguous.
• The verification result: the rendered image, the check report with its denominators and not_run entries, and a list of what remains if the loop ran out.
• A list of what was deliberately left out (connectors above all).
• On request, a detail view and an executive view of one model, or a reproduction of a reference picture with a fidelity report.

Tools it relies on

• The binding loader, resolver and resolution helpers Engine: Notation bindings
• The composers (compose_layered_bands, compose_lanes, compose_nested_grid, compose_radial, compose_two_column_cycle, and the four additional ones compose_matrix, compose_radial_tree, compose_chevron_stack, compose_treemap) Engine: Composition modules
• create_diagram_in_language (or create_diagram with a style property), to create the diagram as a bound diagram type: Creating and finding diagrams
• add_elements_to_diagram_bulk, add_connectors_to_diagram_bulk: Placing elements and connectors
• set_diagram_object_appearance: Element appearance
• set_diagram_link, set_diagram_links_bulk, collapse_parallel_connectors, expand_parallel_connectors: Connector presentation
• set_diagram_display: Diagram display
• layout_diagram, neaten_diagram_objects, resize_diagram_objects, for a graph layout: Opening and laying out, Tidying
• verify_diagram: Verifying a diagram
• set_element_appearance (model-wide; use sparingly): Elements
• The diagram check and the fidelity comparison Engine: Verification modules. The tool that authors a binding from measurements is described there too.

The helper modules are bundled with the skill and run on the machine where EA runs (local code execution). They need Python 3, and PyYAML for the binding loader.

Sample prompts

1. "Lay out the Westbrook Bank application landscape as a layered diagram, with channels on top, business applications in the middle and the data platform at the bottom."
2. "Build a payments process diagram in BPMN lanes for the Westbrook Retail Onboarding flow, one lane per team. Ask me if any task name will not fit its box."
3. "Make the Westbrook Payments application diagram into an executive view as a second diagram, keeping the detail one as it is."
4. "This diagram came out untidy. Tell me why and fix it, three passes at most."
5. "Show the Westbrook capability map as nested containers by domain, and tell me what each domain contains."
6. "Reproduce this diagram from the attached picture using Westbrook elements, then tell me how faithful it is."

Recommended models

Ratings are guidance based on the kind of reasoning the skill needs, not measured benchmarks.

Checking accuracy and completeness

1. verify_diagram matches the composition. After placing, compare each returned object's rectangle with the composed rectangle for that element id. Correct: every composed element is present at its computed rectangle and the object count equals the number of items composed. Red flags: a missing element, a rectangle of all zeros (the element was placed without coordinates), or coordinates altered by a layout pass (a named layout was used instead of none).
2. The check is clean, and the report says what it checked. Read the errors (must be empty), then warnings and not_run. Check the denominators: roles measured, spacing groups measured, labels measured (boxes judged, not elements checked; compare with the element count) and whether a title convention was stated. A zero denominator means that rule measured nothing. Red flags: "clean" quoted while not_run holds entries nobody read, or a diagram checked with no groupings declared.
3. The render, not the readback. Verify with the SVG and confirm the label rules ran (labels measured above zero; no label-fit entry in not_run). Check colors by reading fill and stroke from the SVG. Red flag: a render-exceeds-rectangle error (EA drew a box wider than its stored rectangle), or a color confirmed only by reading the property back.
4. Fidelity, when reproducing a picture. The comparison returns a report; "faithful" means no errors. Check that matching was declared by reference (not guessed from names), read the not-run and not-read lines, and check that the precision the reading declared is honest. A faithful reproduction need not pass the lint: hand-placed references have irregular spacing the checker will rightly flag, and gating on "clean" for a reproduction is gating on the wrong thing.
5. Binding resolution was stated. The reply must quote the path, confidence and reason, and say what was done for unbound, ambiguous and weak. Red flag: a diagram composed against a binding the resolver declined.
6. Conflicts were asked, not decided. If any unanswered conflict exists, the transcript must show the question put to you before the final composition. Red flag: widened boxes with no question.
7. The loop was bounded and the remainder reported. Count correction passes (three at most) and confirm that if errors remain, the reply lists them rather than saying "done".
8. Completeness of content. Compare the set of element ids on the diagram with the set you asked for (a package, or a list), and confirm that anything deliberately left out (connectors above all) is named in the reply.

Limitations

• Visual judgment is the AI's, and the checker cannot see it. "Clean" means no defect the checker knows how to measure. It does not say the grammar was right, the content belongs on one diagram, names mean anything, a grouping is honest or the layout matches the reader's mental order. Render it and look. The skill's reference lists what the checker cannot see.
• Shape-scripted notations. EA draws MDG-stereotyped elements with shape scripts that emit paths, not rectangles, so label-fit rules mostly stay silent on such diagrams. An element that shares its name with another on the same view is not label-checked. A name colliding with a stereotype icon inside its own box is not reachable by any rule.
• Fill is sometimes unavailable. In the ArchiMate 3 binding's notes, Node and Grouping ignore a per-diagram fill: the write succeeds, the property reads back, and EA paints its own colors. Seven of the nine concepts the notes list honor it. Use Device or SystemSoftware instead of Node for color-coded technology layers.
• A color set as the element default is invisible to the color rule. The unexplained-color rule reads the placement's own style. A diagram colored through EA's Default Appearance dialog reports no fills.
• No arcs. EA's connector vocabulary has no arc, so radial and mind-map diagrams use straight or Bezier lines. The geometry is equivalent; the drawing is not identical to a reference that uses arcs.
• Crossings are approximate. The count is measured center to center. Under orthogonal routing it is neither a lower nor an upper bound on what the reader sees, and two connectors drawn on top of each other are not seen at all. Compare between passes.
• Compartments cannot be removed, only reduced to names.
• Sequence and timing diagrams cannot be generated by composing coordinates. They are recorded as not producible, deliberately.
• The deletion and write risks of the underlying ea_diagram operations apply: baseline first when changing a diagram that matters (ea-change-management).

The engine behind this skill is described in Composition engine.