ea-navigation-diagrams

Logic: AI + AI Power Tools checks. Mostly deterministic writes; the AI scopes the work and decides when to offer it.

What it is for

Use it to make a capability map, taxonomy, organization structure or reference model browsable by people who do not model. You end with a click-through set of diagrams, one per parent, from a landing diagram down to the leaves.

ea-navigation-diagrams turns a hierarchy that already exists in an EA repository into a set of click-through diagrams, one per parent. Double-clicking a parent box on one diagram opens the diagram of its children. Chained across levels, a capability model, taxonomy, organization structure or reference model becomes something a person who does not model can browse: a landing diagram of the top level, each box opening the level below, down to the leaves. It replaces the one big tree diagram, which stops being readable past about thirty elements.

A navigation diagram is an ordinary diagram attached to an element as its child diagram, with the element flagged as composite. On any diagram where that element appears, EA draws a small marker in its bottom-right corner (people call it the eyeglasses or chain-link icon), and double-clicking the element opens the child diagram. It is not a hyperlink element, a diagram frame or a Navigation Cell. Those are different EA features.

The skill is the companion to ea-modeling. That skill builds the model. This one makes the model navigable.

Capabilities it uses

When to use it, and when not

Use it when a repository contains, or has just been loaded with, hierarchical elements (capability models, technology reference models, product or service taxonomies, org structures, requirement and risk breakdowns, data domains, value-stream hierarchies) and you want to browse them by clicking down and not by reading a tree. The AI also offers it proactively, once, when it meets a qualifying hierarchy during other work.

The skill applies when all of these hold:

1. The repository contains a parent and child hierarchy. That is element parentage, a containment connector (PartOf, Aggregation, Composition, Decomposition, or an MDG equivalent), or a level tag (Level, Tier, Depth).
2. The hierarchy is more than one level deep and has more than about a dozen elements. Below that, one diagram is better.
3. The hierarchy is reasonably stable. Navigation diagrams are cheap to rebuild, and they do need rebuilding when the hierarchy changes.

How it works

The composite mechanism. Two facts, stored in two places, must agree, and both are required.

A child link alone gives a diagram that is owned by the element and appears under it in the Browser, but the element shows no marker and does not navigate on double-click. The composite flag alone points at nothing. A repository with hand-built navigation diagrams often holds a mix of the two, so the skill audits before it extends anyone's existing pattern. The diagram's parent is the owning element, not a parent diagram or a package, which stays independent. An element-owned diagram appears in the Browser under the element and not in the package's diagram list, so it does not clutter the package and cannot collide with a same-named package-level diagram.

The audit. find_composite_diagram_mismatches scans a package (and by default its whole subtree) and reports each element where the two halves disagree: a child diagram exists but the flag is not set (it looks navigable in the Browser and does not drill down), or the flag is set but no child diagram exists (a marker that opens nothing). Elements with neither half are ordinary leaves, not mismatches. A flag-missing mismatch is fixed with set_composite_diagram, not by hand. The skill calls this audit the highest-value check it has. It is what would catch the case where only some elements in a hand-built set (for example 6 of 21) were navigable. It runs the audit before extending any existing set, and offers it whenever you ask about navigation diagrams in a repository the AI did not build.

When the AI offers this unprompted. This is conversational behavior. No operation asks a question. The AI offers only while riding on work it was already doing, and never makes a call whose only purpose is to scan for hierarchies to pitch.

1. Trigger. AI At the end of an operation that creates elements with parentage or containment (a bulk create with parents, a spreadsheet or XMI import), or when a read it was already making reveals a hierarchy.
2. Threshold. AI All three must hold, or the AI says nothing: depth of two or more levels; more than 12 elements in scope; three or more elements that have children. The AI applies the thresholds to data already in hand.
3. Check what is already navigable. AI Power Tools It runs the audit and counts in-scope parents that already have both halves. If every qualifying parent is already navigable, it says nothing, and it does not re-prompt on a package that is done.
4. Say what it found, then offer exactly four choices. (AI, you) It states scope, diagram count and target package before you answer. The four choices, every time: build the full set; complete an existing set, matching the styling of diagrams already there; fix only the flags, the cheap and safe choice that sets the composite flag where a child diagram already exists and nothing else; or no thanks, remembered for the rest of the session. A standing "never offer this" covers every package.
5. Fire once. Once per load or per analyzed package, never inside a loop.

Accepting is not done until a rendered image confirms it.

Always confirm the source of truth first. AI A model can hold the hierarchy in element parentage and in connectors, and they can disagree. Element parentage is what EA's Browser and nesting render from, so it is preferred. The AI says which it used and reports a disagreement and does not silently pick one.

The build. Six phases:

1. Read the hierarchy. AI Power Tools One query pulls each element, its parent and its level tag. From it: roots (no parent in scope), parents (at least one child; these get a diagram and the flag), and leaves (no children, no diagram, no flag). The diagram count is one landing diagram plus one per parent.
2. Pick or copy a template. (AI + AI Power Tools) If the repository already has a navigation diagram you like, the AI copies its diagram type, display settings and style, including the MDG diagram profile, the theme and the connector-label suppression that keeps the picture clean. With no template, a default is a Logical diagram that suppresses connector labels and stereotypes and shows icons and shapes.
3. Create the diagram rows. AI Power Tools One diagram per parent, plus one landing diagram in the package. Each child diagram is named after its element. The AI inserts only the identifying details first, then sets the bulky repeated settings in a single follow-up over the batch, tagging the batch so the follow-up finds exactly these rows, and reads back the assigned identifier for each. It never assumes identifiers are contiguous.
4. Place the objects. (AI computes geometry, AI Power Tools places) One add_elements_to_diagram_bulk call per diagram, with the container and its children in one list.
5. Flag the parents composite. AI Power Tools set_composite_diagram per parent, after that parent's child diagram exists. It writes both halves in one call, so they cannot land out of sync the way two separate writes can, and reports whether a read-back from both halves is consistent. A success with a "not consistent" flag means the write did not fully land and needs investigating. It is idempotent. Passing an explicit empty diagram clears the link (the child diagrams are un-parented and the flag is reset). Leaves stay unflagged, which is correct, and no marker tells the person there is nothing below. The skill forbids setting the flag by hand, because that sets only one half.
6. Verify and refresh. (AI + AI Power Tools) A count, then a render of the landing diagram, a mid-level diagram and a leaf-level diagram. Then the Browser is reloaded and the diagrams are looked at in EA. AI with computer use; otherwise you

The nested-container layout. Each child diagram holds the parent drawn as a large container with its immediate children laid out inside it. There are no connectors. The nesting already expresses the hierarchy, and connectors turn the picture back into the tree diagram this replaces. The landing diagram is the same grid with no container, with the roots laid out directly. The AI computes the geometry:

The container is sized from the columns and rows, and child i sits at its column and row inside it. Stacking order matters: the container gets the highest stacking number and the children 1 to n, or the container paints over them. Per-placement style is carried with each placement. The container takes the stereotype default fill and the children take a contrasting fill, and that contrast is the visual cue for "the thing you drilled into" against "the things you can drill into next". Colors are stored as blue-green-red integers and not red-green-blue, so a color value read directly looks reversed.

Placement settings that matter. add_elements_to_diagram_bulk takes per-element position and style and an explicit layout opt-out. The AI passes "no layout" explicitly: a layout pass would re-run EA's automatic layout and overwrite the computed positions, destroying the nested arrangement. It passes "no automatic connectors" as well, because the default draws every connector whose both ends are now on the diagram, which reintroduces the tree. The call is idempotent per element (an already-placed element is skipped) and a failure on one entry does not abort the batch.

Verification. The AI checks that the number of diagrams equals 1 plus the parents; the number of placed objects equals the roots plus, for every parent, 1 plus its children; no placement is unstyled; there are no stray connector entries; and the number of composite elements equals the number of parents. Then it renders at least the landing diagram, one mid-level and one leaf-level diagram, and looks: the marker is present on every box that should drill down, the children sit inside the container, and no name is clipped. Counting rows is not verification. The deliverable is a picture. EA caches diagrams it has already rendered, so a diagram written directly and previously opened renders stale. The AI reloads before rendering, or uses verify_diagram, which always reloads. The package is then reloaded in the Browser (right-click the package, Contents, Reload Current Package), or the model is reopened, because writes to the repository do not reach an EA session that has the package cached. AI with computer use; otherwise you It re-runs the audit after the build and expects zero mismatches.

Rebuilding after the hierarchy changes. Navigation diagrams are derived artifacts. A new parent needs a diagram and the flag. An element that lost all its children should have its diagram removed and its flag cleared, or it navigates to an empty picture. A renamed element should have its child diagram renamed. Moved children need their placements rewritten on both the old and the new parent's diagram. The cheapest correct approach is to regenerate the whole set for the affected package, identified so a regeneration can find and replace exactly its own output. The AI never deletes your existing diagrams to make room. It moves superseded diagrams to a clearly named holding package inside the same scope, tells you what moved and why, and lets you do the deleting. You Baseline first with ea-change-management when regenerating over an existing set.

Known traps.

Reporting back. The AI tells you, in plain language, how many diagrams were created and where, which elements are now navigable and which are leaves, what the entry-point diagram is called, how many were already navigable against newly flagged when it fixed an existing set, and that the Browser needs a reload.

What you get

• A landing diagram and one child diagram per parent, each parent flagged so that double-clicking drills down.
• A summary: how many diagrams, where they are, which elements are navigable, the entry-point diagram.
• A rendered check of the landing, a mid-level and a leaf-level diagram.
• Superseded diagrams moved to a holding package, not deleted.

Tools it relies on

• find_composite_diagram_mismatches and set_composite_diagram (Composite and navigation diagrams): audit both halves, and write or clear both together with a read-back.
• add_elements_to_diagram_bulk (Placing elements and connectors): place a container and its children with explicit geometry, stacking order and style.
• create_diagram and update_diagram (Creating and finding diagrams): the API route to a diagram, with the owning element among its properties.
• reload_diagram, get_diagram_png and verify_diagram (Opening and laying out, Verifying a diagram): refresh the render cache and look at the result.
• execute_sql and describe_table (Direct queries): read the hierarchy, set the repeated diagram settings, and run the counts.
• create_package (Packages): staging or holding packages. list_elements_in_package (Elements) and summarize_connector_patterns (Summaries) are the natural hook points for the proactive offer.
• Shared reference: ea-ui-verification.md.

Sample prompts

1. "Check whether the capability hierarchy under Consumer Banking in Westbrook Bank is actually navigable." Runs the audit over the package and reports counts and mismatches.
2. "Fix the Consumer Banking drill-down flags. Don't build anything new." Fixes only the flags: sets the flag where a child diagram exists, then re-audits.
3. "I just loaded the Westbrook capability model. Make it browsable by clicking down through levels." Reads the hierarchy, builds the landing diagram and one diagram per parent, flags each parent, renders three diagrams, and reports.
4. "Some boxes on the Lending diagram show the little chain icon but double-click opens Properties. Why?" Audits for a flag with no diagram, then reports that the default-diagram issue described under Limitations may apply.
5. "The capability model changed: two parents lost their children and one was renamed. Update the navigation set." Regenerates for the affected package, clears flags on the emptied parents, renames the child diagram, and moves superseded diagrams to a holding package without deleting.
6. "Extend the existing navigation set so new level-3 capabilities are covered, matching the existing look." Completes the existing set: reads an existing diagram's type, display settings and style, generates only what is missing, and verifies.

Recommended models

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

Checking accuracy and completeness

1. The mismatch audit is clean. After the build, run find_composite_diagram_mismatches over the scope. Correct: no mismatches, and the number of elements checked equals the elements in scope. Red flag: any "diagram without flag" or "flag without diagram".
2. Counts match the hierarchy. Correct: diagrams equal 1 plus the parents; placed objects equal the roots plus, over all parents, 1 plus children; none unstyled; no stray connector entries; composites equal the parents. Derive the expected numbers from the first read of the hierarchy, not from the build output.
3. Every set_composite_diagram response said consistent. A single "not consistent" is an unresolved defect.
4. Rendered pictures. verify_diagram for the landing diagram, one mid-level and one leaf-level diagram. Correct: markers present on every box that should drill down, children inside the container, no clipped names, no connectors. Reload first, because a diagram rendered before the write can be stale.
5. Nothing deleted. Complete: the diagrams and elements that existed before the run are unchanged apart from the new set, and superseded diagrams are in the holding package.
6. Leaves are leaves. No diagram is owned by a leaf element, and leaves are unflagged.
7. Round trip in EA. AI with computer use; otherwise you Double-click a marked box in EA and confirm the child diagram opens. This is the only check that exercises the behavior you want. See Limitations.

Limitations

• Drill-down may also need a default-diagram entry. On some models the composite marker is drawn but double-click opens the element's Properties and not the child diagram. If double-click does not navigate even though the audit reports no mismatch, the AI says so and checks in EA, and does not tell you the set is working on the strength of the audit alone. Rendering and the audit both pass in that situation, which is why the round-trip check matters.
• The diagram rows are created with direct database writes for a batch. create_diagram and update_diagram are the API route. Direct writes change the database under EA's open session, which does not resync until reloaded, hence the Browser reload.
• A diagram written directly and previously opened renders stale until reloaded. verify_diagram always reloads.
• The Browser must be reloaded after the set is built. The reload is done in EA's window. AI with computer use; otherwise you
• Placing with connectors turned off does not fully suppress connector drawing. EA still draws a relationship between two placed elements, and a stored entry can appear if a layout runs. Pass "no layout" as the skill does. The response warns when entries survive.
• A set does not update itself when the hierarchy changes. It is regenerated.
• The thresholds are judgment. The 12-element, two-level and three-parent thresholds are the skill's choice, not an EA limit.
• Windows only, with EA running. The server attaches to a running EA. Starting EA and opening the model is a separate step (ea-start-here).