ieevisualizer-report-figures
Use when an agent prepares figures and text for a recurring company report or management briefing with ieeVisualizer, or answers a reader's follow-up question about one: classifies each item as monito
SKILL.mdskills/ieevisualizer-report-figures/SKILL.md
GitHubReport figures for recurring briefings
The output is not "a report was sent". It is "a decision-maker saw a specific change, understood how sure we are, and made a better decision with little extra effort". Every figure, sentence and section is judged against that.
Who owns what
| Owner | Responsibility |
|---|---|
| Host reporting workflow (e.g. a scheduled job runner) | schedule and cadence, permissions, recipient filtering, approval, delivery |
| Domain systems and analytics | authoritative data and every computed metric, interval and forecast |
| ieeVisualizer | visual form, templates, themes, rendering, export, manifests |
| The agent (you) | choose items and forms, bind evidence, inspect figures, write the explanation |
You never compute a business metric inside the figure step, never widen access beyond the permission-filtered evidence you were given, and never send anything externally without the host's approval step.
Step 1: classify every candidate item
| Class | Test | Treatment |
|---|---|---|
| Monitoring | metric within its normal range vs the stated base | one line in the top block; no figure unless a trend is the point |
| Exception | outside normal range, a threshold crossed, or a source failed | lede + one figure + caveat + decision request |
| Exploration | a reader asked a question | answer first, then evidence; reuse existing artifacts |
"Normal range" must be defined (e.g. same weeks last year ± the historical
spread, or a threshold the readers set), not felt. A failed source is
always an exception: say so and show no figure for it (figure-is-a-claim).
Step 2: evidence → figure → caveat → decision
For each exception or exploration item:
- Evidence. The computed values, with provenance and the comparison
base. Run
when-numbers-lie-audit. - Figure only if it shows something a sentence cannot
(
chart-choice-by-relationship); build withieevisualizer-figures; put the report run id inspec.metadataand the provenance. Render with the organisation's registered report theme, looked up withthemes.list_themes()rather than a name hardcoded in the skill or the report code, and pin it asname@versionso a re-render matches what was sent. - Caveat. One sentence naming the main thing that could make the figure misleading or the competing explanation.
- Decision. What the readers could do, the owner, and when the question can be settled. Or "no action".
Step 3: assemble
Use company-report-structure: the four-line top block (what changed, why
it matters, what is uncertain, what warrants action), then exceptions, then
explorations, then method. Prose in editorial-voice-wsj-like; numbers in
numbers-style; every headline checked by headline-and-deck; final pass
with figure-review-redteam.
Metric traps (generic examples, illustrative)
Every recurring metric needs a written definition before it is reported. Typical traps, using an online shop as the example:
| Metric | Define | Common trap |
|---|---|---|
| Orders | paid orders, by date of payment | counting by order date vs delivery date mixes two series |
| Lead-to-order conversion | orders / leads, same cohort | immature cohorts: recent leads have not had time to convert |
| Revenue, revenue per order | € excl. VAT, recognised on a stated date | average of regional averages; restatements after late refunds |
| Ad spend per order (CPA), ROAS | spend / attributed orders, named attribution window | window changes; platform-reported vs observed conversions |
| On-time delivery | deliveries within the promised window / deliveries | deliveries with no recorded time silently excluded |
| Return rate | returns by order month / orders | returns arrive weeks later: the latest month is incomplete |
| Capacity utilisation | booked hours / available hours | missing shift data read as zero availability or zero use |
| Budget burn | spend / budget | a nullable budget column where null means "no budget set" is undefined, not 0% |
Follow-up questions
When a reader asks "why did conversion fall?":
- Reopen the report's artifacts (spec + frozen snapshot) rather than starting from a screenshot.
- Compare with preceding periods and the same period last year.
- Segment where the data permits (channel, region, cohort, device) and decompose rate vs mix.
- Check the usual suspects: tracking or attribution change, price change, traffic quality, response latency, seasonality, immature cohorts.
- Report supported findings with uncertainty. Name a likely cause only as
far as the design allows (
statistical-claims), and say what would verify it (a holdout, a week more data, a reconciliation). - A refreshed analysis is a new artifact; the sent figures stay as they were.
No autonomous bureaucracy
- Do not create new recurring reports, sections or charts on your own initiative. Propose them; humans decide.
- A quiet period gets a short monitoring note (or nothing, if that is the agreed rule), not padding.
- Prefer one decisive figure to five descriptive ones.
- Prefer human approval for external distribution, sensitive data and consequential recommendations.
- Usefulness is measured by questions resolved, time to explanation and decisions supported, not by reports, pages or charts produced.
Good / bad
Bad: 14-chart weekly PDF covering every metric, each titled with the metric name, sent automatically every Monday. Good: top block with three monitoring lines and one exception ("Meta ads attribution export failed; ad spend per order unavailable this week"), one figure for the conversion change with its caveat, and a decision request.
Checklist
- Every item classified monitoring / exception / exploration against a defined base.
- Source failures reported as exceptions with no figure.
- Each exception: evidence, at most one figure, one caveat, one decision with owner.
- Figures built with
ieevisualizer-figures, inspected, run id in metadata. - Theme looked up from the registry and pinned by version, not hardcoded by name.
- Top block written last and checked against the body.
- Follow-ups reuse frozen artifacts; refreshed analyses are new artifacts.
- Nothing added for completeness; nothing sent without the host's approval.
Adapted in part from ieeVisualizer's own documentation (docs/, MIT);
changed: rewritten as an agent procedure with generic examples.
Sources and licences: SOURCES.md.