ea-help

Logic: AI + AI Power Tools checks. The AI reads documentation and drives the interface; AI Power Tools reads the version and the state back.

What it is for

Use it to do a Sparx EA task no other skill covers, such as element appearance, wizard pages or a setting that exists only in a dialog. You end with the task done by Sparx's own documented procedure for your EA version, and the outcome checked through a different route.

ea-help is the documented fallback for a Sparx EA task that no other skill covers. It identifies the running EA version and repository type, finds the written procedure in Sparx's own user guide for that exact version, carries the procedure out in EA's user interface, and verifies the outcome through a different route from the one it acted on.

The server covers a large part of EA and ea-com covers more. What is left is real: element appearance, wizard pages, dialog-only settings, anything EA exposes only through its interface. This skill closes that gap with Sparx's documentation in place of a half-remembered menu path.

It has one hard requirement. The guide must match the running EA version. Menu paths, ribbon panels and dialog names move between versions, and a procedure read from the wrong version's guide is followed confidently and wrongly. When the version cannot be matched, the skill stops and says so.

Capabilities it uses

When to use it, and when not

This skill is the last resort. Use it only when all three of these are true:

1. No skill in the routing map covers the task.
2. No operation does the job. Check MCP server: tools and operations to be sure.
3. COM does not expose it either. Check ea-com before concluding the automation interface has no route.

The rule is that three routes exist for any EA task: a server operation, the COM automation interface, and the user interface. A limitation is real only when all three fail. "There is no operation" is not a limitation. It is a reason to check the other two.

When the AI ends up here it says so in one line, for example "No skill covers this, so I am working from the EA 17.1 user guide", so that nobody mistakes a documented fallback for a supported path.

How it works

1. Confirm this is the gap. AI The AI runs the three-route check and states in one line that it is using the user guide.

2. Establish the EA version. (AI Power Tools, then AI) The AI calls get_repository_info and reads the EA version. The guide is published per major and minor version, so a reported 17.1.1716 resolves to 17.1. Three situations stop the work: EA is not running or the call fails (there is no version to match); the version resolves to a guide that does not exist (the AI says which version it could not find and does not fall back to the nearest version); or the version was given rather than read, which makes it unconfirmed, so the AI confirms it before driving anything. The AI states the version it resolved before using it.

3. Establish the repository type. AI The same task can have different instructions against a local file (.qea or .qeax), a server connection, or a cloud connection, where Enterprise Architect reaches a shared repository through Pro Cloud Server. For AI Power Tools, a cloud connection behaves the same as a server connection. The AI reads the project path and connection string and classifies the connection. If it is ambiguous, the AI asks. You Version and repository type are carried into every later step and restated with the procedure.

4. Resolve the guide for that version. (AI, through the client's fetch capability) Two traps both return success. The bare version address redirects to the newest version's welcome page. A wrong or renamed page under a real version also redirects to that version's welcome page and does not report a missing page. The rule that survives both: check the final address after redirects. It must still carry the requested version and page. If it landed on a welcome page, the page was not served.

5. Find the page. (AI, through the client's fetch capability) Sparx publishes a full-text search over the guide, and each version publishes a sitemap. The AI searches first and falls back to the sitemap. The search index is fixed to one version that is not necessarily yours, so the AI uses a result only to find the page, then rebuilds the address for your version and verifies it. Short queries of two to four plain words work; long queries and exact phrases return nothing, so the AI shortens rather than rephrases. It never reads the guide in bulk: it extracts the block it needs.

6. Present the procedure, then act. (AI, you) The AI states which guide version the procedure came from, which repository type it assumes, and the steps in EA's own wording. Then the procedure is carried out. AI with computer use; otherwise you

   • With computer use, it follows the steps as written, takes a screenshot after any step that opens a dialog or advances a wizard page, confirms it is on the screen the guide names, and matches controls by label and not position. A ribbon path that does not lead where the guide says means the version does not match, so the AI stops and re-checks step 2 and does not hunt for a similar control.
   • Without computer use, the AI does not report the task as blocked. It hands you the whole procedure in EA's wording and asks for one specific observation: the dialog, field or list whose contents decide the next step. For a dialog, you paste a screenshot of it into the conversation so the AI can read it. Your answer replaces the screenshot the AI would have taken. You
   • Anything destructive (baseline restores, deletes, technology re-imports, overwrite prompts) needs a statement of what will change and in which repository, and your agreement, before the click that commits it. You

7. Verify the outcome, not the steps. (AI + AI Power Tools) Following the guide correctly is not evidence that the task succeeded, and a user-interface action can complete against the wrong object. The AI verifies through a different route from the one it used:

   What changed	How it is confirmed
   Element or connector properties	get_element, reading the field back
   Tagged values	get_element_tags
   Anything else	A direct query against the table that holds it
   A technology's live state	assess_mdg_situation, or get_mdg_from_runtime for one technology
   A file EA wrote	Read the file and check it holds what the procedure said it would
   Anything visual	A screenshot of the diagram (AI with computer use; otherwise you looking)

   If verification and the interface disagree, verification wins, and the AI reports what it read back.

8. When the guide does not answer, say so. AI The guide documents EA's interface thoroughly and the internal structure of the files it writes unevenly. A clear "the documentation does not specify this" is worth more than a plausible reconstruction, which will be tried, will fail, and will cost a cycle to rule out. The AI records what it searched and read, checks the automation interface pages (one page per COM class) before giving up, and re-checks the other two routes.

What you get

• A statement of the EA version and repository type the procedure assumes.
• The documented procedure in EA's own wording, carried out in the interface (with computer use) or handed to you step by step (without it).
• A read-back that confirms the outcome through a different route, or an honest statement that the guide does not cover the question.

Tools it relies on

• get_repository_info (Project): EA version, project path and connection string.
• get_element and get_element_tags (Elements, Tagged values): read-back of properties and tags.
• execute_sql (Direct queries): read-back for any other change, protected by the SQL guard.
• assess_mdg_situation and get_mdg_from_runtime (Discovering technologies): technology state.
• Computer use, when available: driving EA's interface.
• The client's browser or fetch capability: reading the Sparx user guide.
• Shared references: operations.md and ea-ui-verification.md.

Sample prompts

These all assume the task has already been through routing and no skill or operation covers it.

1. "What does EA need to restore a baseline? The restore reports success but the package is unchanged." Resolves the version and repository type, finds the compare and merge pages, extracts the relevant block, and reads the package back.
2. "Set the background color of this element in the interface the way EA documents it, then check it took." Finds the documented route, drives it, and verifies through a read from a different route than the dialog.
3. "I'm on EA 16.1, not 17. Walk me through creating a technology selection file." Resolves 16.1, checks that guide version exists, notes the repository type, and gives the procedure for you to run if computer use is not available.
4. "Does the user guide say what is inside an MDG technology selection file?" The documented honest negative: the guide describes the wizard and not the file format, and the AI reports that.
5. "No operation covers this dialog. Do it for me, and tell me exactly what you will click first." Presents the procedure with version and repository type, then asks before the committing click.

Recommended models

Ratings are guidance based on the kind of reasoning the skill needs, not measured benchmarks. Driving the interface through screenshots is slow and benefits from a model that keeps the version, repository type and step in mind together.

Checking accuracy and completeness

1. Version stated and matched. Correct: the AI's first message names the resolved major and minor version, equal to what get_repository_info reported. Red flag: a version no call returned, or a silent use of a nearby version.
2. The final address. For every page the AI cites, the address after redirects carries the same version and page. Red flag: a citation that actually landed on the welcome page.
3. The presented procedure. Correct: it names the guide version, the repository type and the steps in EA's wording before any click. Red flag: acting first, or paraphrased control labels.
4. Read-back from a different route. After a change, compare yourself: query the table that holds it with execute_sql and look at EA. Correct: the value matches the intent. Red flag: "done" on the strength of the dialog closing.
5. Honest negatives. Ask a question the guide does not answer, such as a file format. Correct: the AI says the documentation does not specify it and lists what it searched. Red flag: a confident reconstruction.
6. Destructive steps. Correct: before a baseline restore, delete or overwrite, the AI states the effect and the repository and waits. Check the transcript.
7. No computer use. With computer use off, correct is that the AI hands over the procedure and asks for a specific observation. Red flag: it reports "blocked" or "done".

Limitations

• It is slower and less verifiable than any operation. It works through the user interface from documentation. Use it only for the gap.
• It needs network access and a real browser context. The Sparx site can serve a browser-check page to a plain fetch tool. If a fetch returns a short "checking your browser" document, that is what happened, and it is not a missing page. When the site cannot be reached, the AI says so and stops. It does not rebuild a menu path from memory.
• The search index is fixed to one guide version, not necessarily yours, and works only for short queries.
• The guide is thorough on the interface and uneven on file formats. Some answers do not exist in it.
• The guide is fetched live and never cached. A version's guide can be republished in place, and a stale copy would produce exactly the failure the skill exists to prevent.
• Computer use is needed to drive the interface. Without it, the AI hands the procedure to you.
• A blocking dialog shows only in EA's window. A call that hangs usually means a dialog is open. With computer use the AI reads the dialog from EA's window, uses its message to correct the call and dismisses it. Without it, you take a screenshot of the dialog and paste it into the conversation so the AI can analyze it, then you dismiss the dialog so processing can continue. See ea-ui-verification.md.
• Section folder names in the guide change between versions. Swapping only the version in a working address is a first guess and must be verified.