Data Visualization Quality

Create visualizations that answer the requested analytical question. A valid chart specification is not automatically publishable.

Decide before designing

Establish four things before choosing a visual:

1. Claim: the comparison, trend, distribution, composition, relationship, or decision the user wants to understand.
2. Required evidence: the dimensions, measures, units, denominators, time windows, and comparable populations needed to support that claim.
3. Coverage: which required fields and entities are complete, partial, unavailable, pending, reported, or calculated.
4. Smallest useful surface: prose, compact table, one chart, small multiples, or a genuinely interactive explorer.

Classify the outcome:

• Complete: available comparable data directly supports the requested claim.
• Partial: a clearly bounded subset supports a useful part of the claim.
• Unavailable: the central requested measure or denominator is absent.
• Unsupported: the source or analytical method cannot answer the request.

For unavailable or unsupported outcomes, do not create a chart or data explorer. Explain the missing evidence and offer the best recovery action. A private run receipt may preserve the attempt, but it is not a visualization.

Preserve semantic fidelity

• Never substitute an adjacent measure merely because it exists. Issued tickets are not attendance; totals are not concentration; cumulative counts are not velocity; ticket counts are not revenue.
• Never imply comparability across unlike cohorts, definitions, currencies, denominators, tier taxonomies, or time windows. Normalize, facet, or decline.
• Keep observed, reported, calculated, estimated, pending, and unavailable values distinguishable.
• Do not coerce missing evidence to zero.
• State material caveats next to the claim they limit.

Require a visual to earn its space

Use a visual only when it makes a meaningful relationship easier to understand than concise prose or a compact table.

Do not publish:

• a chart whose only surviving measure answers a different question;
• a table dominated by repeated Unavailable, N/A, or coverage prose;
• a large chart for a few values that are clearer in one sentence;
• prose, chart, and table that redundantly repeat the same information;
• decorative KPI cards, controls, legends, or panels that do not aid a decision;
• a normal success workspace around an unavailable result.

In production pipelines, implement deterministic publishability validation. Skill instructions and model self-assessment are not sufficient enforcement. Keep exact thresholds schema-aware and tested: absence of one central measure can invalidate an analysis even when most cells are populated.

Choose and design the form

Read references/chart-design.md when selecting or reviewing chart form, scales, ordering, labels, interaction, responsive layout, accessibility, or exports. Skip it when the correct result is prose-only or an unavailable receipt.

Product-state contract

Match product status to analytical outcome, not merely execution completion.

• Complete visualizations may expose appropriate interactive and export actions.
• Partial visualizations must label their bounded coverage and omissions.
• Unavailable or unsupported results should be compact, remove irrelevant chart/share/export/filter controls, and offer a recovery action.
• Do not call a receipt-only result a dashboard, explorer, or completed analysis.
• Strip internal visualization specifications from fallback prose. Do not show a raw Markdown table when the product owns structured table rendering.

Verify

For production work, validate:

• the visual answers the current request rather than an adjacent one;
• units, scales, denominators, sorting, normalization, and precision;
• missing and partial coverage behavior;
• labels, marks, legends, tooltips, and accessible fallback text;
• realistic desktop and mobile rendering;
• malformed, oversized, duplicate, unavailable-dominated, and metric- substitution rejection paths;
• source validation, application publication, provider delivery, and visible rendering as separate claims.

Use demonstrated bad outputs as regression fixtures. A polished misleading visualization is a more dangerous failure than an explicit refusal to chart.