prol-dashboards

What it is for

Use it to give stakeholders a Prolaborate dashboard over the repository. You end with widgets each backed by a verified query, and a layout plan for you to arrange the tiles.

prol-dashboards builds, reads and changes Prolaborate dashboards through the web interface. A Prolaborate dashboard is a four-column grid of widgets over an EA repository. Each widget is a tile that holds one or more content blocks. The skill chooses the right widget for a question, writes the query each widget type requires, verifies the query before saving, and hands you a layout plan.

It does not author model content. A chart counts elements that already exist. Creating or changing those elements is EA work (see ea-start-here).

Capabilities it uses

When to use it, and when not

Use it when the task names a Prolaborate dashboard, widget, chart, card or report tile, or asks what a dashboard shows. Run prol-start-here first in the session.

How it works

1. Probe the data first. (AI Power Tools, AI interprets) The AI runs one census query, then targeted probes, in the chart wizard's query console. The result rules chart types in and out before any is built.
2. Choose the widget. AI Guided by a fixed question-to-widget table. A "how many by" question gets a bar or column chart, a proportion gets a pie or donut (seven values or fewer), a hierarchy gets a landscape, one number gets a card, and so on. The AI reports what the data cannot support instead of building a chart that hides it.
3. Write the query for the widget's contract. (AI, AI Power Tools checks) The AI writes a read-only database query. Prolaborate's own "view sample" prints the contract and a complete example for the chosen chart type, so the AI confirms the contract from Prolaborate, not from memory, and confirms the repository's SQL dialect first.
4. Build the widget in the interface. (AI driving the browser) Add the widget, name the tile, configure the chart. For a chart the type is picked before anything else, because changing the type afterward wipes the name and the query.
5. Execute and read. AI Power Tools The AI runs the query in the console and reads the row count and the actual values. This is the honest check.
6. Work the presentation step. AI Three presentation controls change the data, not the styling (see below).
7. Save twice. AI The chart is saved, then the dashboard is saved. They are separate saves.
8. Verify from a different surface. AI Power Tools The AI re-opens the widget's configuration, and where useful reads the dashboard definition, to confirm what persisted. A success response is a claim, not evidence.
9. Hand back a layout plan. (AI, you) The AI lists each tile with its column, row, width and height, and says plainly that the layout is yours to apply.

Two cautions apply throughout. The small gear inside the widget body is its configuration; the gear in the tile header is cosmetics only. And editing a generated query is a one-way door, so the chart type is settled first.

Widget and chart catalog

The widget catalog has 11 entries. Charts is one of them, and the 13 chart types live inside it. Confusing the two lists is a common error.

Only Charts, Reports and Cards take a query. The others are configured, not queried. The Dashboards widget embeds a live nested dashboard: the inner dashboard re-executes all its own widgets, compresses rather than scrolls, and drops the inner tile titles. A dashboard cannot embed itself. Nesting several levels deep is allowed.

The 13 chart types:

Which chart for which question:

Queries and Prolaborate's contract

Charts, Reports and Cards each take a read-only database query run against the repository's own database. There is no single contract. There are five families, and the family is a property of the chart type, so it cannot be predicted from how a chart looks.

Reports use the axial family without the series. The row hyperlink and element icon need the display column named exactly as Prolaborate expects, plus the element's identifier, type and stereotype.

Rules that decide whether a chart is right:

• The chart aggregates, the query does not. Return one row per element (or per relationship pair). Prolaborate groups by series and counts rows.
• With a group name present, the group name is the axis category and the series is the color. The designer's labels suggest the opposite.
• Casing differs by family for the group-name column.
• A hand-written Road Map must emit dates month first. Prolaborate's own sample says day first and is wrong. With the wrong order, only rows with a day-of-month of 12 or less draw, which looks like sparse data.
• Duplicate group names collapse in a Road Map. One bar survives per distinct value. It is a key, not a lane.
• A Card takes one value, named cards. For a percentage, set the symbol and suffix in the presentation step; a text result breaks the card.
• Bubble axes must be numeric. The designer accepts a text property without complaint and produces hundreds of series and one visible bubble.
• Where the sample's prose disagrees with its generated query, trust the generated query. The prose was wrong in both cases tested.

Getting the contract from Prolaborate. In the chart wizard, select the chart type, skip to the query step, then use "view sample". It prints that type's contract and a complete query in both SQL Server and MySQL forms. No data and no source selection are needed.

Dialect belongs to the repository. One Prolaborate instance can front repositories on different engines (MySQL, MariaDB, SQL Server, PostgreSQL, SQLite). A dialect error is reported as "No results found", which is indistinguishable from an empty result. The AI establishes the dialect first.

One real restriction. A query that does not begin with a plain select is refused. There are no common table expressions, temporary tables or procedures. Recursion is unrolled into one branch per level. Other apparent blocks are dialect mismatches.

Top-N. Bar and Column have no top-N or sort setting, so limiting happens in the query. The skill teaches a ranking function that works on current MySQL, MariaDB, SQL Server and SQLite versions, because the limit keywords share no syntax.

An example in words (Westbrook Bank). A criticality split as a Pie: one row per WBABusinessApplication element, with the criticality tagged value as its series, and the chart counts them. A stacked column of criticality (color) by lifecycle (axis) adds the lifecycle as the group name. A card for total applications is a count of those elements. This is an illustration; substitute your own technology, stereotypes and tags.

Data probes

Every chart type has a precondition that is invisible until you look, and none of them fail loudly. Each produces a chart that renders and is wrong or unreadable. The probes run in the chart wizard's query console and are cancelled without saving.

Reading rules that matter:

• A column is a usable measure only when it is numeric and varies. In testing, one tag held thousands of numeric values and exactly one distinct value, which makes every bubble the same size.
• Do not filter connectors by type to find a hierarchy. A hierarchy is often an Aggregation, and a type filter hides it. The check is that parent-child connectors equal elements minus roots.
• Do not assume how a connector stereotype is stored. Element stereotypes are stored bare. A technology declaring a connector stereotype does not mean it is stored qualified: on the Westbrook Bank reference model the technology declares Uses, Flows and realizes, and the connectors still store them as bare names, with the binding to the technology recorded separately. Others, such as part-of, come from no technology at all. The AI reads the resolved value from the console's output instead of guessing either form, because a filter written for one form fails silently on the other. The same check applies when a chart's numbers disagree with the model.
• The tagged-value usability probe uses a pattern-matching feature available only on MySQL and MariaDB. It is the least portable query in the skill.

Cardinality thresholds are convention, not measured limits of Prolaborate:

One threshold is a finding rather than a convention: Nested Pie and Heat Map need a hand-typed label-to-color row for each value, so many values is unreasonable work regardless of readability.

Presentation controls that change the data

Most of the presentation step is cosmetic. Three controls are not, and all three fail silently.

Also: Build Chart by Percentage or Value on Pie and Donut decides whether slices read as shares or counts. Minimum and Maximum Radius on Bubble are diameters. On a Road Map, the display date format controls the axis and is a different setting from the date format that parses the data. Landscape and Nested Pie legends list level labels, which default to Level-0, Level-1, so the AI renames them before they reach the reader. Formatting such as percent signs belongs to the widget and not to the query.

Layout

The canvas is a four-column grid. Every new tile lands 1x1, regardless of widget type. A chart or landscape is unreadable at 1x1, so layout is a required finishing step.

You apply the layout. Resizing and moving a tile needs a drag that emits intermediate mouse movements. With the browser control used in verification, a single click-drag was ignored with no error, so the AI does not retry it or report a layout as applied.

What the AI hands back is a plan in grid units (column, row, width, height). For example, for a Westbrook Bank portfolio dashboard:

It tells you three things, each of which is easy to miss:

1. Drag from the crosshair handle in the tile header, not from the tile body.
2. Resizing pushes other tiles, and the push cascades. Nothing is overwritten, but one resize displaced four tiles across two columns in testing. Work top to bottom so each push disturbs only tiles not yet placed.
3. Save the dashboard afterward. Layout persists only through the page-level Save.

Sizing guidance: a tile with several Card blocks needs at least 1x2 or the lower cards clip behind a scrollbar; Reports need two columns or more; Text, Rich Text, Hyperlinks and Images are fine at 1x1. On a narrow screen the four columns collapse to a single stack, so placement order becomes reading order, and the plan places tiles in reading order.

Reading a dashboard without opening it

Opening a dashboard in the interface is the most expensive thing to do. Prolaborate can return a dashboard's whole definition (every widget, block, color and grid position) in one structured read. The definition gives shape, not numbers: content resolves per block at display time. To read a saved chart's query, the AI uses the widget's configuration option to view the query source.

Facts that matter if the AI parses the definition:

• Write is not read. The create call uses a different vocabulary from the read, so a read-modify-write round trip is broken by design. The skill builds through the interface and writes field by field.
• Some read fields mislead. The dashboard settings come back as the literal text "null", and the modified-date field is always zeroed; the real timestamp is in a different field, in US month-first order.
• A block's binding to a saved report lives inside its notes. That field also holds a Text block's HTML. The AI never touches the notes of a block it did not author, because rewriting it destroys a chart block's binding and queries.
• Confirm a widget type's payload before writing it. The AI adds that widget once through the interface and captures what Prolaborate sends.

What you get

• A dashboard with the requested widgets, each verified by row count and values.
• A statement of what persisted, re-read from a different surface.
• A layout plan in grid units, with the statement that you apply the layout.
• A note for each chart the data could not support, and why.

Tools it relies on

• Browser control, to drive the dashboard editor and the chart wizard
• The chart wizard's query console, to run probes and verify each query by row count and values
• "View sample", Prolaborate's own contract and generated query in SQL Server and MySQL forms
• Prolaborate's dashboard read, to inspect a dashboard's structure without opening it
• The preflight in prol-start-here

No server operation is used. The EA tools that create the model content a chart counts are in ea_model.

Sample prompts

1. Reads the dashboard definition and lists tiles, blocks and positions.

2. Writes a one-value query, executes and reads the number, builds the card, saves both the card and the dashboard.

3. Pushes back, because Westbrook has 14 stereotypes (above the readable limit for a Pie), and offers a Bar, a top-N, or a Pie over criticality.

4. Runs the census, builds four cards, a Pie, a Stacked Column with lifecycle on the axis and a top-10 Column, then returns a layout plan.

5. Probes for date-like tagged values. If there are none, it says so and does not build the chart.

6. Returns the target geometry in grid units with the three notes, and says the layout is yours to apply.

The dashboard, application and model 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. Probe before build. The transcript shows the census (or an equivalent probe) before the first widget. Red flag: a chart chosen with no data reading.
2. The Execute row count matches the rendered chart. For each chart, compare the row count and a sample of values with the saved tile. A Road Map silently drops rows whose date fails to parse, so count its bars against the rows.
3. Independent count. For a card, ask for a separate count of the same elements in EA or through the console and compare. Red flag: a figure that agrees with expectation but came from a join that matches nothing. The skill's worked example reports that a roll-up once returned exactly the expected figure because its join matched nothing, so also run one query that would return zero or an absurd value if the assumption were wrong.
4. Persistence. Re-open each widget's configuration after saving and compare with what was entered. Settings have failed to persist silently. Reload the dashboard and confirm both the chart save and the dashboard save landed.
5. Contract and dialect. The query's columns match the chart family's contract, and the dialect was established first. Red flag: No results found reported as "the data has no matching rows".
6. Traps avoided. No Nested Pie or Heat Map for a "which is biggest" question; Stacked Column has lifecycle on the axis and criticality as the color; MDG Based Report is off for a hand-written Report; Landscape levels are renamed; no connector-type filter was used to find a hierarchy.
7. Honest layout statement. The final message states that tiles are 1x1 until you apply the plan. Red flag: it says the dashboard is finished or the layout is applied.

The skill ships a test suite of 24 cases in three groups: end-to-end builds, selection and contract traps, and honesty and limits.

Limitations

• You apply the layout. Every dashboard needs manual arrangement, because the browser control used in verification could not perform the drag. This is not a limit of Prolaborate.
• One repository, one dialect. Everything was verified against MySQL. "View sample" prints the SQL Server form. The tagged-value usability probe will not run on SQL Server as written.
• Verified as Super Admin. A restricted user may see less.
• Two blocked widgets. Lifecycle Road Map needs a Life Cycle Management definition bound to a stereotype. Integration Reports needs an integration registered by the tenant owner, which requires external-system credentials. The AI reports the block, never enters credentials for an external system, and does not substitute a different widget silently.
• The cardinality thresholds are convention.
• The Rich Text Security toggle is a render-time filter only. Its block-list covers script, frame and inline-handler markup.
• Editing a referenced query inside a block is reported to detach it from the saved report.

See also Limitations and known issues.