ea-diagram-advisor

Logic: AI + AI Power Tools checks. The AI measures the scope and talks to you; a rule-based module ranks the candidate views.

What it is for

Use it to decide, before anything is drawn, which diagram type and viewpoint shows what you want to understand. You end with a ranked recommendation with its reasoning, ready to hand to ea-diagram-composition.

ea-diagram-advisor answers the question that comes before drawing: which diagram type and viewpoint should this be? You say what you want to understand ("show me the application landscape for payments"). You should not need to know which of dozens of diagram types, across several modeling languages, expresses it.

The skill turns that request into a ranked recommendation with its reasoning attached. It never draws anything. When the choice is made, the result is handed to ea-diagram-composition.

Three rules shape everything it does:

• Measure the content, never guess it. The method is to profile what is in the scope, attribute each element to a modeling language, and let that decide whether a conformant view exists at all.
• Recommend and explain; never silently decide. If you asked for a specific diagram type you get that type, with a note when it fits badly. A recommender that quietly picks is indistinguishable from one that is wrong.
• Report the gaps. A scope that cannot be fully attributed, a view the toolchain cannot generate, and a scope that spans several languages are each stated, not smoothed over.

Capabilities it uses

When to use it, and when not

Use it when someone describes what they want to see rather than naming a diagram type, or before generating a diagram over content whose modeling languages you have not checked. Run ea-start-here first in the session.

How it works

1. (you, then AI Power Tools) Measure the scope. You say which package or packages the diagram is about; choosing the scope is your call. AI Power Tools counts the stereotypes in that scope (stereotype, base type and number of elements) and fetches each technology's vocabulary with get_mdg_from_runtime.
2. Engine Profile the scope. The advisor engine attributes each stereotype to a modeling language and answers the pivotal question: is this scope one modeling language or several? This is rule-based.
3. (engine, AI presents) Recommend. The engine returns a ranked list of options, each with the arithmetic behind it. The AI shows the reasoning and does not paraphrase it away. It uses your wording of the request to break ties.
4. AI Handle the no-conformant-view case. When the scope spans several languages, the engine returns a deliberate non-standard recommendation with two obligations attached: a sentence recording the non-conformance, and the concepts a validation run will flag. The AI says so, records the sentence on the diagram, and offers to reconcile with validation before generating.
5. You Choose. The ranking cannot see what the diagram is for. You pick an option; the AI hands the chosen viewpoint and diagram type to ea-diagram-composition.

What the AI watches for when measuring a scope. The three repository-wide summary operations (summarize_stereotype_usage, summarize_connector_patterns, summarize_observed_metaclasses) describe the whole repository and take no scope, so the count for a scope comes from a direct query. These traps are each measured:

• Every value comes back as text, so counts must be converted.
• The total of the stereotype count is not the scope size, because it excludes unstereotyped elements. A share ("40% unattributed") quoted against the wrong denominator is worse than none. If the scope size matters, it is queried separately.
• get_mdg_from_runtime takes the technology id, not the display name; the display name is reported as unknown. A technology that is loaded but unreadable gives an empty vocabulary, and an unknown one gives none, and a loaded technology can still expose nothing, so an empty vocabulary does not prove an empty technology.
• Neither MDG discovery operation is reliable for a model-embedded MDG. If a technology visible in the model is not listed, the AI reads the technology ids out of the repository instead of concluding it is absent.
• traverse_element_subgraph returns every interior edge twice. The AI removes duplicates before counting connectors.
• Three silent failures return a plausible empty answer instead of an error: a bad element id gives no nodes, a package id passed where an element id was wanted returns a package node, and an unknown stereotype gives a count of zero. An empty profile therefore means "check the scope", never "the scope is empty".

What you get

• The profile of the scope: which modeling languages it holds, each language's share, the stereotypes nothing could attribute, and the total measured.
• A ranked list of options, each with its reasoning: counts, shares, coverage, matched words from your request, and the concepts the view would not admit.
• For a mixed scope: the statement that no conformant single view exists, up to three non-standard options in preference order, the non-conformance sentence, and the concepts a validation run will flag.
• For each option, whether it can be generated and how; an option that cannot be generated is still listed so you know what the content wants to be shown as.

Tools it relies on

• execute_sql for the scope's stereotype counts: Direct queries
• get_mdg_from_runtime for each technology's vocabulary: Discovering technologies
• traverse_element_subgraph, when the scope is defined by relationships rather than packages: Graph and traceability
• The ranking engine (needs local code execution): Diagram advisor engine
• The notation bindings, which hold each notation's view catalogue, concept names and stereotype prefix: Notation bindings
• ea_validate audit, after a non-conformant recommendation, to compare actual findings with the predicted ones: ea_validate

The advisor calls no EA operation itself.

Sample prompts

1. "Which diagram should I use to show how Westbrook Bank's payment applications depend on each other?"
2. "I need to show the Retail Banking packages to the architecture board. Pick the diagram type and tell me why."
3. "Before you generate anything from the Payments package, check which modeling languages are in there."
4. "The Payments package mixes ArchiMate application components with WBA::WBABusinessApplication elements. What diagram can I draw without it being non-conformant?"
5. "Draw me a layered view of the Westbrook application landscape, then tell me what the validator will complain about before you generate it."

Recommended models

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

Checking accuracy and completeness

1. Histogram denominator. Ask for the scope's stereotype count and, separately, the scope's total element count. Correct: the profile's total equals the stereotype count (not the scope size), and any "unattributed" percentage is stated against the stereotyped total. Red flag: a percentage quoted over the unfiltered scope size.
2. Attribution completeness. Read the list of unattributed stereotypes before trusting the recommendation. Correct: it is empty or explained. Red flag: a large share under "unbound" or "ambiguous" with a recommendation presented as confident.
3. Vocabulary supplied. Confirm each technology's vocabulary came from get_mdg_from_runtime for the id. Without it, attribution falls back to the concepts a binding happens to name, and a binding names only what departs from its defaults, so the commonest concept in a language can go unattributed.
4. Reasoning shown. Every recommendation's reasons name counts, shares and coverage arithmetic. Red flag: reasoning that could have been written without looking at the content.
5. Close calls declared. In a small scope several viewpoints may admit everything present. Correct: a "close call" line appears when two options tie on coverage and intent, and you were asked to choose.
6. Generation stated. For each option, read whether it can be generated and how. A "cannot be generated" option must carry that statement and the AI must have said so. Never promise a generated diagram for it.
7. Non-conformance recorded. For any option with a non-conformance sentence, confirm the sentence is on the diagram (for example in a note) and in the reply, and that the predicted findings were offered for scoping out before generation. After generation, run ea_validate audit over the package that holds the content and compare its findings with the prediction. An unpredicted finding means the profile missed something.

Limitations

• The view catalogue is ArchiMate 3's. The ranking works on a notation's declared viewpoints. Of the 11 shipped notation bindings, ArchiMate 3 declares viewpoints (19 of them). For a scope that is homogeneous in any other bound notation, the standard branch produces nothing and the result is the neutral-custom option.
• Coverage is not fitness. Coverage says a view can hold the content, never that it should.
• A recommendation over unmeasured content is a guess. If the scope could not be profiled, the skill must say the recommendation is weak.
• The advisor knows only bound technologies by name. A customer's own MDG can be named only when its vocabulary is supplied; the recommendation for it is neutral-custom.
• Concept counts are keyed on the bare concept name. If two technologies share a concept name, the count used for scoring is the sum across both.
• The ranking cannot see what the diagram is for. It uses only coverage, overlap between your words and the viewpoint, and view narrowness.
• ea_validate audit scopes to a package, not a diagram. The reconciliation compares predicted findings with an audit of the package holding the content.
• A bad scope returns plausible-looking empty results from several operations (see step 1), so an empty profile always needs investigation first.

The engine behind this skill is described in Diagram advisor engine.