figure-is-a-claim
Use before putting any number, KPI tile, chart, table cell or sparkline in front of a reader, and whenever data is missing, partial, failed to load, not yet collected or not applicable. Decides betwee
SKILL.mdskills/figure-is-a-claim/SKILL.md
GitHubEvery drawn value is a claim
Anything you draw (a digit in a tile, the height of a bar, a point on a line) tells the reader that someone measured it and got that value. When a broken data feed falls back to zero, the reader sees a zero and reasons from it; nothing on the page separates it from a genuine zero. Decide what each value is before drawing it. The other skills in this library assume that decision was made here.
The five states of a value
Classify every value before drawing it. Only the first is drawn as a number.
| State | Meaning | Show |
|---|---|---|
| Measured | Source returned a value for this period/segment | the value, with unit |
| Measured zero | Source returned, and the count/sum really is 0 | 0, and say it is real if it is surprising |
| Missing | Should exist, did not arrive (export failed, late batch) | a gap + note naming the cause |
| Not collected | Nothing records it (yet) | omit the panel, or one sentence saying there is no data |
| Not applicable | Undefined (rate with zero denominator, budget not set) | n/a or "no budget set", never 0 |
A nullable budget column where null means "no budget set" is not 0, and a burn rate against it is undefined, not 0%.
Rules
- No default-to-zero.
COALESCE(x, 0),fillna(0),?? 0,or 0on a measure that feeds a figure is a defect unless the source semantics say a missing row is a zero (e.g. no order rows for a day the shop was open and the export succeeded). Write that justification next to the code. - Failed source → no figure, not an empty one. If the request for a panel's data failed, the panel says it failed (and when it last succeeded). It does not render axes with nothing on them.
- Gaps stay gaps. Do not interpolate, carry forward or join points across a missing period unless the figure says so in the caption, and draw the imputed part distinctly.
- Rates need their denominator. A conversion rate with denominator 0 is
undefined. A rate on a small denominator is shown with its
n(seenumbers-style). - Partial periods are labelled or dropped. The current week on Wednesday
is not a week (see
when-numbers-lie-audit). - Keep engineering notes off the page. When a panel has nothing to show, say so in one plain sentence ("No ad-spend data for this period.") and stop. Which table is missing and what someone should build belongs in the team's backlog, not in front of the reader.
- Values are computed; words interpret them. Every number in a chart or a sentence comes out of a query or calculation. An agent writing the narrative quotes those results and never supplies a number of its own.
- Placeholders never ship. Mock arrays, example values and template defaults are removed or visibly marked before a figure leaves the workspace. A synthetic dataset says "synthetic" in its provenance.
Where ieeVisualizer enforces this
- Missing values are
nulland staynull;NaNbecomesnull(ieeVisualizer.spec, docs/SPEC.md "Columns"). - The matplotlib renderer never draws
nullas 0: lines break, bars with no value are labelled "no data", heatmap cells stay blank, and each case adds anull_values_omittedwarning on theRenderResult(docs/RENDERING.md "Missing data"). - A layer with no complete row is a
RenderError(empty_series), andvalidate()reportsall_null_columnandempty_datasetas errors. - Templates refuse
all_null_columnand warnempty_series.
What it does not enforce: whether a 0 in your data is a real zero. If you
filled nulls with zeros upstream, the library draws them faithfully. That
check is yours.
Good / bad
Bad: weekly ad spend tile shows €0 because the Google Ads sync failed.
Good: tile reads "Ad spend: no data (sync failed 6 Oct; last complete week 28
Sep–4 Oct: €1,240)".
Bad: team utilisation chart for October with a flat line at 0% for teams whose shift data has not been imported. Good: those teams are absent from the chart and the caption says "3 of 7 teams: shift data not imported for October."
Bad: eval table shows 0.0 accuracy for a benchmark that timed out.
Good: cell shows — with footnote "run timed out after 6 h; not scored".
Checklist
- Every drawn value is in state Measured or Measured zero.
- Grep the data path for
fillna(0),COALESCE(..., 0),?? 0,or 0; each hit has a written justification or is removed. - Failed or partial sources produce a stated gap, not an empty chart.
- No rate is shown with a zero or unstated denominator.
- No-data text is one plain sentence, with no engineering to-do list.
- Every number in the narrative traces to a query result or computed field.
-
RenderResult.warningswere read; eachnull_values_omittedis explained in the caption or text.
Adapted in part from K-Dense scientific-visualization (MIT) and UK
Analysis Function chart guidance (OGL v3.0); changed: rewritten around the
measured/zero/missing distinction, examples replaced. Sources and licences:
SOURCES.md.