eda-storytelling

name

eda-storytelling

description

Turn a finished analysis into something a person reads and acts on — lead with the finding that settles the question or moves the decision, trace every number back to a run/findings.jsonl, run/changelog.jsonl or run/manifest.json record, and cut the rest. Works from whatever the analysis produced — one flat export, twelve joined tables, a warehouse table queried in place, an index frame over a corpus, a fitted model's posterior. Carries the data-validation verdict, the data-cleaning change log and any stage nobody ran into the writeup as caveats instead of burying them. Use when a single data question has to be answered in one chat reply, when writing up an analysis, when drafting a report, summary or readout of what the data or a fitted model showed, or when a pile of charts and tables needs an argument.

EDA storytelling

The failure is the stats dump: nine charts, a describe() transcript, a correlation matrix, no argument. It reads as thorough and is unusable — the reader cannot tell which of forty numbers mattered, so acts on none. You consume exploratory-data-analysis's run/findings.jsonl and the run/validation.json verdict, and emit one document: what is at stake, and the numbers that settle it.

Applies to whatever the analysis produced: one flat export, twelve joined tables, a 4 GB log nobody loaded, a warehouse table queried in place, an index frame over 500 emails. A skipped stage is a caveat, not a silence — the record behind a number may be a manifest entry, a validation check, a change-log row or a findings row, and a stage nobody ran is named, with why. Enter here when there are numbers and a reader; stop here — you are the last stage.

Every number traces to a record, or it does not ship

A claim with no run/findings.jsonl or run/changelog.jsonl row behind it is a fabricated number, however sure you are you computed it earlier — recalled values come back rounded, pre-cleaning, or carrying the wrong n. Cite by id while drafting, strip the markers in the final pass, and check between:

import json, re
from pathlib import Path
rows = [json.loads(line)
        for p in (Path("run/findings.jsonl"), Path("run/changelog.jsonl")) if p.exists()
        for line in p.read_text().splitlines() if line.strip()]
man = Path("run/manifest.json")            # a row count traces to a source entry
ids = ({r.get("id") or r["op"] for r in rows}
       | (set(json.loads(man.read_text())) if man.exists() else set()))
cited = set(re.findall(r"\[([a-z][a-z0-9_-]*)\](?!\()", Path("draft.md").read_text()))
assert not cited - ids, f"claims with no backing record: {sorted(cited - ids)}"

Recompute an unbacked number and append its row, or delete the sentence — there is no third fix. Scale the trail to the data, never the checks: a paste answered inline has no run/ to cite, and every number in it is computed this turn.

Lead with the finding that settles the question

Name what is at stake in the first two sentences — the decision the reader is choosing between, or, in diagnostic or scientific work, the question they asked — then the finding that moves it. Method and n follow in the same paragraph, never as a preamble; order by how much a finding moves the answer, not by pipeline stage. Cutting is the skill: of thirty findings two reach the reader, the rest stay in run/findings.jsonl. When the data cannot settle the question, that is the headline — "this cannot tell you whether the campaign worked, because exposure was never recorded" is a deliverable, and at n=40 so is "these 40 points cannot separate a trend from noise".

Every chart answers a question you already asked in the prose

The sentence before states the question, the chart answers it, the one after says what it means. If you cannot write that question, cut the chart — it exists because it was easy to make. One claim per chart, never two.

State the uncertainty once, beside the number, then stop

Carry the n and the caveat from the finding's row into the sentence making the claim; a limitation covering the whole analysis is stated once, in the caveats block. Hedging every sentence says nothing while looking careful.

• Round to what n supports: 41% of 11,731, not 41.0126%.
• Say measured or estimated; anything imputed or fitted is estimated, and a number resting on a definition you chose — a 30-minute session window, a funnel step order, a complaint taxonomy — names that definition beside it.
• Give an association its direction and size. Significance and cause are model output: cite the model that produced them, or do not write them in.

Carry the verdict and the change log in as caveats, not footnotes

From run/validation.json: a waived check that could move a reported number is a caveat, stated at that number; an unresolved FAIL is not a caveat — the claim does not ship. Cite change-log rows as "312 duplicates dropped, earliest kept".

Change-log row	Tell the reader	Why
imputation, outlier treatment, a derived label or category, drops hitting a reported segment	yes, at the claim	it can bias the number they act on
dedup removing more than 1% of rows	yes, once in the caveats	it moves every denominator
dtype coercion, whitespace strip, rename, the terminal write-clean row	no	it cannot change a reported number

A stage nobody ran is a caveat too, and it is a required line, not a mood. Every writeup ends with one literal line naming both sides:

Stages: ingestion, validation (pass) · skipped: cleaning (nothing to treat), EDA (not asked)

Write it even when nothing was skipped — then it reads skipped: none, and the reader learns the chain ran rather than guessing. Interrogating a claim that the data is already clean is not the same as validating it: if you did not write run/validation.json this turn, validation is skipped, however clean the data looked. Write up what ran; do not run the rest to tidy the line away.

The same numbers, twice

❌ everything computed, nothing decided
11,731 rows x 14 cols. email 41.0% null | phone 12.3% null | source 0.0% null
Spearman: email_missing~signup_year 0.62, order_value~tenure 0.31, ...
[8 charts] The data shows interesting patterns. Further analysis is recommended.

✅ the same findings.jsonl rows, written for a reader
We cannot email 41% of the customer list, and the gap is not random.

Of 11,731 customers, 4,810 have no email, almost all from the 2023 partner
backfill: 89% of those rows lack one against 6% of normal signups. So a campaign
here reaches about 6,900 people, not 11,700, and it drops partner-sourced
customers, who spend more per order (median $84 against $61, n=11,731). Budget
for the smaller reach, or pull emails from the partner feed first — the excluded
segment is the higher-value one. All figures are measured, none imputed; the 312
dropped duplicate order_ids move every count by under 3%.

Sentences that never ship:

• "Correlation does not imply causation" instead of stating the correlation.
• Any conclusion the reader cannot check against a number you gave them.

Pick the medium, then hand the rendering off

One finding answers in the chat reply; a client deliverable is a PDF report styled by pymc-artifact-style; to poke at the data they want a notebook (marimo_notebooks). Both land in /mnt/session/outputs/, per file-handling.

Common failure modes

Symptom	Likely cause	Fix
User replies "so what?"	No question or decision named; findings ordered by pipeline stage	Open with what is at stake and the one finding that moves it
A number in the draft has no backing row	It came from a scrolled-away cell or from memory	Recompute and append the row with its how, or cut the sentence
A claim rests on a stage nobody ran	Validation or cleaning was skipped and the writeup does not say so	Name the skipped stage as a caveat at that claim, or run it
Every sentence hedges	Uncertainty restated per sentence instead of once per claim	One caveat at the claim; global limits go in the caveats block once
Reader acts on a number cleaning invented	Imputed values reported as measured	Label the layer estimated and cite the imputation change-log row
A conclusion asserts cause	An EDA correlation written up as a mechanism	Give direction and size; a causal claim needs a model, cited as one