ea-stakeholder-reporting

What it is for

Use it to answer a stakeholder's question from the model in their terms, such as "how many applications are mission-critical?" or "what is on this diagram?". You end with an answer in business language, with the coverage that says how far the number, or the diagram's description, can be trusted. Nothing in the model changes.

ea-stakeholder-reporting turns an EA model into an answer a non-modeler can act on: roll-ups by tagged value, a plain-language summary of one element, a diagram in words, and business display terms in place of stereotype and tag names. A stakeholder asks "how many applications are mission-critical?" or "what is in scope for this regulation?". The model holds the data in stereotype names and tagged-value keys. The skill translates, and it adds the one thing translation does not fix: a roll-up is only as honest as its tagged value is complete, and nothing in a raw result warns you when it is not. The same discipline applies to a diagram's description, which is only worth quoting while it matches the diagram.

It is read-only. Nothing in it creates, updates or deletes anything. It uses no code engine and no business layer: every figure comes from asking EA directly through the AI Power Tools MCP Server for Sparx EA.

Capabilities it uses

When to use it, and when not

Use it for a counting or grouping question, for a plain-language fact about one system, for a plain-language answer to "what is on this diagram?", and before presenting any number derived from a tagged value. The coverage check belongs in front of every roll-up, not only the ones that look suspicious.

A comma-joined tag is not a reason to move to the business layer. The business layer also keeps a comma-joined text tag as one value in its column, and only a tag the technology declares as a list of referenced elements is split into rows. This skill's split roll-up is the direct way to count such a tag.

How it works

1. Run the session preflight. AI Power Tools ea-start-here confirms the server is alive, which model is open and which technologies are active, if that has not been done in this session.
2. Check coverage before quoting a number. (AI Power Tools, then AI) summarize_stereotype_usage gives the true count per stereotype, which is the denominator. summarize_tagged_value_usage gives, per tagged value on that stereotype, how many elements carry it, how many have a non-blank value (the populated count, which is the coverage figure), how many distinct values exist, and sample values. A tag missing from the summary is not tracked on that stereotype. The AI compares the populated count with the denominator.
3. Roll up. AI Power Tools aggregate_portfolio groups the elements of a stereotype by a tagged value. The AI scopes it to a package when the question concerns one line of business (the response echoes the scope it covered), and asks for counts only once the element names are not needed.
4. Handle comma-joined values. (AI Power Tools, then AI) The roll-up reports how many of the matched elements hold a comma-joined value. When that count is not zero, the AI rolls up again with the values split, so each element is counted under every part of its value. The groups then sum to more than the total, so the AI quotes each group against the total and not against the sum, and says that it split.
5. Scan the groups. AI A blank group means "not recorded" and is never shown as a category. The literal value None means "assessed and not in scope", which is a different answer from blank. Near-duplicate spellings, such as one team name written with a plain ampersand and with an encoded one, split one real group in two.
6. Describe one element. AI Power Tools get_element_business_view returns the element's stereotype, its tagged values and its connections as "uses" and "used by". A property that is not set is absent from the list, so a short list may mean "never populated" and not "not applicable".
7. Say what a diagram shows. (AI Power Tools, then AI) The description stored with a diagram is the plain-language answer: its first sentence is a one-line summary, and the body lists every element by its business kind and name and every relationship as a sentence. The audit says whether the words can be trusted, so the AI reads the audit before it quotes the description (see below). It quotes the words and not the marker lines that bracket them. A diagram with no description gets the same words generated for this one answer, and the AI says they were generated and are not stored. Storing them in the diagram's notes is a model write, so the AI offers it in one line and, with your yes, hands it to ea-import-export.
8. Translate names into business terms. (AI Power Tools, then AI) For a technology your organization built, the business view and the roll-up label their output with technical names: they use the same lookup as resolve_display_term, which knows the languages that ship with EA and a technology's stereotypes only once that technology's file has been parsed in the session, and never knows a technology's tagged values. So the AI takes a stereotype's business name from the alias the technology declares, read with get_mdg_from_runtime, and derives a tag's label by splitting its name (businessOwner becomes "Business Owner") and dropping the technology prefix from a stereotype with no alias. It uses resolve_display_term for terms from a language that ships with EA.
9. Report the figure with its coverage. AI The number, the denominator, the populated fraction, the scope, and anything that makes the figure incomplete. It does not present a roll-up as complete when the check showed a gap. You You decide whether a partial figure is usable, whether the scope is the one you meant, and whether the question has outgrown this skill and belongs in the business layer.

Describing a diagram for someone who cannot see it

A diagram's description is plain text in the diagram's notes that says what it shows, in the organization's business terms and with nothing about how it is drawn. It is written for readers who cannot see the picture or do not have EA: a screen reader, a document, an AI assistant, a stakeholder. The skill uses it as the answer to "what is on this diagram?" instead of reading shapes and stereotype names aloud. The operations that create and refresh descriptions, and the full set of statuses, are in Diagram descriptions.

The status comes before the quote, as coverage comes before a count.

A description can also leave things out. When the audit finds that the text omits elements or relationships the diagram holds, the AI tells the reader what it leaves out and does not present the text as the whole picture. That holds for a description a person wrote by hand as much as for a generated one.

An out-of-date description is not refreshed from here. The AI says it is out of date and names ea-import-export, where a refresh previews first and keeps a person's edits.

Why the coverage check comes first

A roll-up over a tagged value that is set on only some elements of a type returns a confident, wrong number. It does not fail and it does not warn. Three different coverage failures look identical in the output.

A fourth failure is invisible to counting. When a tag takes free text, two spellings of one value split a real group in two. On the reference model a technical-owner tag held one team name on six systems and the same name with an encoded ampersand, left over from an import, on two. The tag is fully populated, and a team-by-team roll-up reports two teams where the truth is one team with eight. The AI scans the distinct values, not only the counts.

An empty roll-up is ambiguous: either the stereotype does not exist, or it exists and never sets that tag. The result does not say which, so the AI confirms the stereotype name against the usage summary before reporting a zero to anyone.

The figures below were measured on the Westbrook Bank reference model. They show the shape of a result and are not numbers to expect from your model.

What each operation gives you

• summarize_stereotype_usage lists each stereotype with the number of elements and the element type it sits on. It also resolves each stereotype through the technology it is bound to, says whether each application is bound to a technology or ad hoc, lists names that appear both ways, and counts elements carrying more than one stereotype. See Summaries.
• summarize_tagged_value_usage takes an optional stereotype. Per tagged value it reports how many are present, how many are populated, how many distinct values exist, and sample values. "Present" is not "populated": EA creates a tagged value when a stereotype is applied whether or not anyone fills it in.
• aggregate_portfolio groups the elements of one stereotype by one tagged value. You can scope it to a package and its whole subtree, ask for counts only, restrict it to technology-bound or ad hoc applications, and split comma-joined values. It reports the total, the groups ordered by count, how many elements hold a comma-joined value, and the scope it actually covered. The tag name is matched without regard to case. See Project.
• get_element_business_view describes one element: its type, its properties and its connections as "uses" and "used by". A property that is not set on the element is absent from the list. See Business view.
• resolve_display_term maps a stereotype, a tag, a connector stereotype or a diagram type to its display name, and returns the technical name unchanged when it finds nothing. It covers the languages that ship with EA, plus the stereotypes of a technology whose file was parsed in the session. It never resolves a technology's tags. A kind it does not recognize comes back as "not found", exactly like a genuine miss. See Display terms.
• audit_diagram_descriptions reports, for every diagram in a package (for one diagram, its package), whether its description is current, out of date, missing or written by a person, and what the text leaves out. It reads and writes nothing. See Diagram descriptions.
• get_diagram_manifest returns a whole diagram in one reading. This skill uses it for the diagram's description, with a statement of whether the words are the stored ones or were generated just now, and asks for no picture. See Reading a diagram or a package as a manifest.
• get_mdg_from_runtime returns each of your technology's stereotypes with the alias it declares, which is the business name to use. See Discovering technologies.

Behaviors to keep in mind, measured on the reference model:

• A misspelled or nonexistent stereotype gives the same zero result as a real stereotype that never sets the tag.
• A blank value is a legitimate group. Scan for it before reading the rest.
• None and blank are different answers. On the reference model the regulatory-scope tag uses the literal value None for "assessed, not in scope" and blank for "never assessed". Do not merge them.
• Scope explicitly. On the reference model the whole-repository count of business applications was 52, and scoped to the Westbrook Bank root package 45; the other seven sat in a scratch area.

The comma-joined case. A tag such as regulatory scope can hold GLBA, FFIEC as one string. Grouped as it comes, GLBA and GLBA, FFIEC are separate groups, so "how many applications are in GLBA scope" is not the GLBA group. On the reference model the exact GLBA group held 14 business applications, and the split roll-up counted 28 in GLBA scope: half the true count sat in combined-value groups. The roll-up's count of comma-joined values is what tells the AI to split. A tag whose values legitimately contain commas, such as a team named Risk, Compliance & Audit, must not be split, and the operation cannot tell the two apart, so the AI looks at the values before splitting.

What you get

• The figure, with its denominator, populated fraction and scope.
• Any blank group named as "not recorded" and not shown as a category, and None kept apart from blank.
• A flag on near-duplicate values that probably belong together.
• For a comma-joined tag, the split figure with a statement that it was split and that the groups overlap.
• For a single system, a plain-language summary of owner, classification and connections, in business terms.
• For a diagram, its description in plain language, with a statement of whether it is current, out of date or generated just now, and what it leaves out.
• A recommendation to move to ea-reporting-database when the figure must be checked against the repository, recurs, or feeds Power BI.

Tools it relies on

• Usage summaries: Summaries
• The roll-up: Project
• One element in business language: Business view
• Display names: Display terms
• A diagram's description and its audit status: Diagram descriptions
• A diagram read whole, for its description: Reading a diagram or a package as a manifest
• Stereotype aliases: get_mdg_from_runtime in Discovering technologies
• Independent spot-checks: Direct queries

Sample prompts

1. Runs the coverage check, then groups by criticality and quotes the figure against the denominator.

2. Rolls up, sees that some elements hold comma-joined values, rolls up again with the values split, and says that it did.

3. Gives the business view for the named element, with the stereotype's alias and readable tag labels in place of technical names.

4. Triggers the near-duplicate scan, because the owner tag is free text.

5. A scoped roll-up that echoes the scope and states the populated fraction.

6. Several roll-ups plus the coverage table. The AI names the gaps instead of hiding them, and recommends the business layer if the figures are to be refreshed or defended.

7. Checks the description's status, then gives the diagram in plain sentences: what it is about, its groupings, each element by its business kind and name, and each relationship. It says if the description is out of date or leaves something out.

8. Audits the package and reports the counts by status and the diagrams that need work, not every row.

The system, package and technology names are illustrations. Replace them with your own.

Recommended models

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

Checking accuracy and completeness

1. The denominator is right. Correct: the denominator comes from the stereotype summary, and for a stereotype with a fully populated tag the roll-up total equals the stereotype's element count. A lower total means the tag is missing on some elements. An element with several stereotypes is counted once per stereotype in both.
2. Populated, not present. For the tag you grouped by, the populated count is compared with the element count, and any shortfall appears in the answer as a fraction. Red flag: a figure quoted with no denominator.
3. An empty roll-up was checked. Correct: the stereotype name was confirmed against the usage summary before a zero was reported, because a misspelled stereotype and an untracked tag both return empty.
4. No hidden blank group, and None kept apart. The AI scans for an empty value and reports it as "not recorded". Red flags: a blank group presented as a category; None and blank merged.
5. No split values. Sort the group values and look for near-duplicates: different case, trailing characters, an encoded character. Two groups that read as one are one finding.
6. The comma-joined count was checked. Correct: the roll-up's count of comma-joined values was read, and when it was not zero the split roll-up was used and each group quoted against the total. Red flag: "GLBA scope" answered from the GLBA group alone.
7. Scope is what you intended. Read the echoed scope (how many packages, how deep) and confirm it matches the part of the tree you meant.
8. Business terms are right. Correct: stereotype names come from the technology's aliases and tag labels are readable words. Red flag: a technical name such as WBABusinessApplication handed to a stakeholder, or a label said to come from the business view for your own technology.
9. Independent count. Ask the AI to confirm one figure with a direct query against the model's stored tagged values for the same stereotype and tag. The two should agree.
10. The description was checked before it was quoted. Correct: the audit status came first, and a description that is out of date, damaged or unreadable was named as such. Red flags: a description quoted as what the diagram shows with no status; an incomplete description presented as the whole diagram; generated words presented as stored ones.
11. The words are about the diagram, not its drawing. Correct: the description names elements by business kind and relationships as sentences. Red flags: shapes, colors, positions or technical stereotype names read out to a stakeholder.

Limitations

• The coverage check is the AI's job. The operations never say a roll-up is partial.
• The empty roll-up is ambiguous between a wrong stereotype name and an untracked tag.
• Your own technology's terms come back as technical names. Tags never resolve through the display-term lookup, and stereotypes resolve only once the technology's file has been parsed in the session. The AI takes aliases from the technology and derives tag labels.
• Splitting is blunt. It splits on commas for the whole tag and cannot tell a multi-value tag from a free-text tag that contains commas.
• A missing property does not explain itself. The business view does not say whether a tag is unset or not tracked on that stereotype; the coverage summary does.
• The audit compares names. It finds a description that leaves something out, and it does not judge whether a person's own text explains the diagram well.
• A diagram with no description gets generated words that are not stored. Storing them is a model write, which belongs to ea-import-export.
• A description is only readable where the technology is. If the diagram's technology cannot be read on the machine running the server, the description is left out and the audit says why.
• Not checked against the repository. These operations read EA directly at one moment. For a figure that has to be defended, or checked cell by cell against an independent read, use ea-reporting-database.