Clean up model decay

Goal

Find orphan elements, composite-diagram links that have fallen out of sync, and inconsistent stereotype or tag use, then fix them without deleting anything that is still load-bearing. This is for a model steward doing a cleanup pass on a long-lived repository. You end with a prioritized list of real decay, a baseline taken before any change, safe fixes applied, and a baseline comparison that shows only the intended changes.

Where it runs

This scenario needs the MCP server. Computer use covers its UI steps.

Before you start

• EA is running with the right model open, and the preflight is done.
• Decide the scope: the smallest package that answers the question. Whole-model scans are slower, especially while other sessions work in the same repository.
• Agree to take a baseline first (ea-change-management) and to review each delete before it runs.

Steps

1. AI with computer use; otherwise you If EA is not running or the model is not open, start EA and open it. AI Power Tools ea-start-here runs the preflight and lists the package tree. You choose the scope package.
2. AI Power Tools ea-change-management takes a baseline of the scope. You accept it.
3. AI Power Tools ea-model-hygiene lists orphans: elements with no connectors (find_orphan_elements, see Elements).
4. AI Power Tools ea-model-hygiene narrows the orphans to real candidates: an element with a real stereotype, no connectors, and no placement on any diagram. This is a rule-based filter.
5. AI Power Tools ea-model-hygiene finds composite-link mismatches in the scope, subtree included (find_composite_diagram_mismatches, see Composite and navigation diagrams).
6. AI Power Tools ea-model-hygiene summarizes stereotype use, tag use, and which base types each stereotype sits on (Summaries).
7. AI ea-model-hygiene interprets the results and separates decay from design choices. You decide what counts as decay in your model.
8. AI Power Tools For each deletion candidate, ea-model-hygiene runs the pre-delete safety checks: what points at it, how far its connections reach, whether it is drawn anywhere or anchors a navigation diagram. You decide delete or keep.
9. AI ea-model-hygiene and ea-modeling carry out the fixes: delete, move, re-sync composite links, correct tags. AI Power Tools makes each edit; You approve per change.
10. AI Power Tools ea-change-management verifies by re-querying and comparing against the baseline.

An orphan scan is not a delete list. find_orphan_elements means one thing: no connectors. It does not mean unused or safe to delete. On Westbrook's capability model it flagged most elements as orphans, almost all legitimate. They were capability containers whose only relationship is parent and child (containment is not a connector), package proxy objects (EA creates a mirror object for every package), and elements related only by diagram placement. A real candidate has a real stereotype, has zero connectors, and appears on no diagram. All three conditions are required.

Step 4, placement. An element drawn on a diagram is not decay even with no connectors. Westbrook draws data lineage as diagram placement rather than connectors, so its data assets all appear as orphans and none is decay. That is a modeling choice, and the scan cannot tell you which you are looking at. Step 7 is where you say.

Step 5, composite links. A mismatch is one of two kinds. A diagram can exist under an element that is not flagged as composite, so double-clicking does not drill down. Or the flag can be set while nothing opens, so the element shows a marker that goes nowhere. Re-sync with the operation that writes both halves together (set_composite_diagram). Load a hierarchy and generate navigation diagrams covers the mechanism.

Step 6, reading the summaries. Read the low end of the stereotype usage summary. A stereotype used once beside a near-identical name used 35 times is a typo or an abandoned convention. Flag it; do not rewrite it without asking. In the tag usage summary, compare the number of elements that have the tag with the number where it is actually filled in. EA creates the tag row when a stereotype is applied whether or not anyone fills it in, so presence alone overstates coverage. A tag that appears on only a few elements of a type needs one more check before you call it decay: whether the technology declares it for that stereotype. A declared tag that few elements fill in is either optional by design or a field only some contributors knew about. A tag the technology does not declare is an ad hoc addition. On the Westbrook reference model, a PCI-scope justification tag is filled in on only a few business applications. The WBA technology declares it on business applications and vendor systems, so it reads as a sparsely filled declared tag, not an ad hoc one; against a technology that did not declare it, the same count would be an ad hoc tag. Read your own technology's declarations rather than assuming either. A stereotype that sits on elements of different EA base types is flagged as mixed.

Step 6, connector stereotypes. The summaries cover element stereotypes only. The assistant counts connectors by stored stereotype with a direct query of the model (Direct queries), and, where local code execution is available, the connector census in Compare declared and observed usage also says which of them are bound to your technology. Two things to know when reading the result:

• EA stores a connector's stereotype by its bare name, bound or not. On the Westbrook reference model, the declared Uses, Flows and realizes are stored exactly so, whether bound to the technology, bound to another language (some Uses connectors are bound to a shipped business-motivation language) or carried ad hoc. The binding is held separately. A count by stored name cannot tell those apart; the census can.
• Informal names and casing drift accumulate on connectors. The same model also carries extends and part-of, which no technology declares, and stores the declared realizes in lower case. A check that compares connector stereotypes as exact strings misses every spelling it does not name. Westbrook's lifecycle governance rule, WBA-LFY-001, flags a dependency from a Strategic or Current element to a Deprecated one when the connector's stereotype is one of four names, one of which is a capitalized Realizes. No connector stores that string, so the rule silently checks fewer connectors than it appears to. That is under-reporting, not false positives, which makes it the harder kind to notice. Flag such a mismatch to the rule's owner; do not rename connectors to fit the rule without asking.

Step 8, the safety sequence. Run it in this order and stop at the first thing found:

1. What points at it. Trace connections into the element, one step. The default direction of the trace is outward, so the assistant must ask for the other way.
2. How far the blast radius goes. A traversal in both directions, to a depth of at most five. The same connection can appear twice, so read nodes and connections as sets.
3. Whether it is drawn anywhere or anchors a navigation diagram, and the composite check over its parent package.
4. Only then delete.

Deleting a package is silent and total: its elements, diagrams and nested packages all go with no per-item confirmation. List the contents first. Moving a subtree is a copy (Copy a package as new) followed by deleting the original.

Step 10. Confirm a deletion by counting: the element's id returns a clean zero, or a scoped re-run of the orphan scan no longer lists it.

Prompts to use

Opening:

Follow-ups:

• Narrow: "Of the orphans, which have a real stereotype, no connectors, and no diagram placement?"
• Interpret: "That near-duplicate stereotype with one element: what is it next to, and what would you ask the owner?"
• Connectors: "List the connector stereotypes the model stores, with counts. Which does our technology declare, and which are informal names or casing variants?"
• Safety: "Run the pre-delete checks on those three elements and show me what points at each."
• Fix: "Delete the two that passed every check, re-sync the composite links, then compare to the baseline."

Recommended models

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

Checking the result

• Correct. For each deletion, the trace showed nothing pointing at the element, no diagram placement, and no composite child diagram. For each composite fix, the mismatch check now returns zero for the package. Red flag: a deletion justified only by "it was an orphan".
• Complete. Counts at each filter stage add up (orphans found minus those excluded, with each exclusion reason). The composite check covers the whole subtree. Red flag: stages whose counts do not add up, or a deep part of the tree that was not scanned.
• Nothing unintended changed. The baseline comparison lists only the deleted and changed items you approved, as "Baseline only" (deleted) and "Changed". Anything else is a problem; stop and review before continuing.

Variations

• Run it on the model root as a quarterly pass, on a cadence you arrange.
• Turn a standing consistency expectation into a ruleset once it is worth enforcing every time (for example, every business application carries all six base tags). See Validate a model against a ruleset.
• Restrict attention to what changed recently, using the change report in Find out what changed, when and by whom.

Limitations

• An orphan scan is not a delete list. Use all three conditions.
• Elements with no stereotype and no connectors include capability containers and package proxies. Do not delete them.
• Connector stereotypes are counted with a direct query of the model (Direct queries), which also finds drift in connector vocabulary (case differences, informal names). Which connectors are bound to your technology needs the connector census in Compare declared and observed usage, which needs local code execution.
• A governance rule that names connector stereotypes as exact strings under-reports when the model's spelling differs. Nothing warns you; compare the names a rule uses with the names the model stores.
• Wide scans can time out when several sessions work the same repository. Retry once, scope smaller, and check EA for a dialog box before concluding anything. With computer use, the assistant sees the dialog in EA's window, reads it, uses the message to correct the call, dismisses the dialog and keeps going. Without computer use, you take a screenshot of the dialog and paste it into the conversation so the assistant can analyze it, then you dismiss the dialog so processing can continue.