Data storytelling

This is the exact file agents read, including the credit header and licence notice. Save it as data-storytelling/SKILL.md.

---
name: data-storytelling
description: >
  Turn an analysis into a narrative that drives a decision, instead of handing over a pile of charts and leaving the audience to find the point. Name the one audience and the single decision, write one governing message, structure it answer-first with the Minto pyramid and an SCQA opening, select the fewest charts that carry the message, make each chart state its own takeaway in its title, write the "so what" and the ask, and check the story does not mislead. Covers explanatory versus exploratory framing, the three-minute story, narrative guidance, hero and villain metrics, annotation and focus, and the written report, slide deck, dashboard-commentary and email forms. Use it when someone says "tell the story in this data", "turn this analysis into a report", "write the exec summary", "present these results", "what's the headline here", "make this deck land", or "nobody got the point of my last report". Do NOT use it to lay out a live dashboard (see dashboard-design), design its filters and drill-downs (see dashboard-filters-interactivity), pick a single chart type (see chart-selection), choose which metrics to track (see metric-selection), or run the analysis that produces the numbers (see the data-analysis skills).
license: Free to use and adapt under CC BY 4.0, with credit to Afeez Adebayo. Link afeezadebayo.com, https://www.linkedin.com/in/afeez-adebayo/ and this skill's page at https://afeezadebayo.com/skills-md/data/dashboards-reporting/data-storytelling/.
---

# Data storytelling

## When to use this, and when not to

Use this skill when the analysis is done and the job is now to make it land: a written report, a slide deck, an executive summary, a commentary layer on a dashboard, or an email that has to move a named person to a decision. The triggers are a request to tell the story in some data, turn an analysis into a report or presentation, write the headline or the executive summary, present results to stakeholders, or a complaint that a previous report was read and then nothing happened.

Do not use it to lay out the dashboard surface itself, which is `dashboard-design`, or to design the filters, drill-downs and linked views on that surface, which is `dashboard-filters-interactivity`. Picking a single chart type is `chart-selection`, choosing which metrics are worth tracking is `metric-selection`, and the analysis that produces the numbers lives in the data-analysis skills. This skill assumes the numbers exist, are correct, and now have to persuade someone to act.

The core idea: a report is not a record of everything you found. It is an argument for a decision, aimed at one audience. A collage of charts leaves the reader to work out what matters and usually they will not, so the finding dies in the deck (juiceanalytics, "How to apply data storytelling to dashboards"). A story states the point first, shows only the evidence that carries it, and says what to do next. Build from the decision backwards, not from the analysis forwards.

## Inputs the agent must have before starting

1. **The audience and the decision.** Who reads this, what they already know, and the single action it should trigger. This input changes every later choice, so ask for it first. "The VP of sales decides in Thursday's review whether to keep funding the mid-market pilot" is enough; "a summary of the Q3 data" is not.
2. **The findings and the numbers behind them.** The actual results, with their definitions and the period they cover, so the story rests on real figures and not a vague recollection. If a figure is missing, ask for it rather than estimating.
3. **The medium and the length limit.** A one-page memo, a six-slide deck, a dashboard commentary box, or a five-line email. The structure is the same; the room you have is not, so fix it now.
4. **The level of certainty.** How solid each finding is, what the sample or caveat is, and whether anything is still provisional. A story that hides its own uncertainty is not persuasive, it is brittle.
5. **The counter-argument.** What someone who disagrees would say, or what the data does not support. Naming it early stops the story being one-sided and makes it survive the room.
6. **Whether the output is sent on someone's behalf.** If the report, deck or email is emailed, published or presented to other people, that is an irreversible action on their behalf and waits for explicit confirmation. Default to a draft.

If the audience or the decision is unknown, stop and ask. Everything downstream is a guess without it.

## The workflow, step by step

### 1. State the audience and the one decision in a sentence

Write a single line: "[audience] will decide [what] on [when/occasion], and this should move them to [action]." If you cannot complete it, you are not ready to write. If the sentence needs an "and" for a second audience with a different decision, that is two outputs, not one, because a deck that serves a board and an engineering team at once serves neither (Minto, via thinkinsights, "Pyramid Principle").

### 2. Write the single governing message

Reduce the whole analysis to one sentence a reader could repeat afterwards. Knaflic calls this the big idea: it states your unique point of view, conveys what is at stake, and is a complete sentence, not a topic (Nussbaumer Knaflic, *Storytelling with Data*). "Mid-market churn rose to 9% last quarter, driven by onboarding delays we can fix, so we should fund two onboarding hires" is a message. "Q3 churn analysis" is a topic.

Decision rule: if the message is longer than one sentence, or contains the word "and" joining two unrelated claims, it is not yet one message. Split it, and pick the one that serves the decision in step 1.

### 3. Structure it answer-first with the pyramid

Lead with the answer, then support it. Busy readers get the conclusion in the first ten seconds, and the direct approach is more persuasive than building up to it (Minto, via thinkinsights). Group the support into about three points that are mutually exclusive and collectively exhaustive, each a summary of the evidence beneath it, ordered by importance.

Open with SCQA to frame why the reader should care before the answer:

- **Situation:** the context both sides already agree on.
- **Complication:** what changed or went wrong, the reason this matters now.
- **Question:** the decision the complication forces.
- **Answer:** the governing message from step 2, which the rest of the output supports.

Decision rule: anything that does not support the governing message is moved to an appendix, not deleted and not left in the body. The body carries the argument; the appendix holds the backup (Minto, via thinkinsights).

### 4. Decide explanatory, not exploratory, and fix the path

A report is explanatory: you know the point and you are leading the reader to it along one path. That is different from an exploratory dashboard, where the reader reaches their own conclusion by interacting (susielu, "Storytelling in dashboards"). Do not hand over your exploration, which is every chart you made in the order you made them. Choose the single path that proves the message.

Decision rule: if you are tempted to include a chart because it was hard to make or is interesting, and it does not advance the message, cut it. Interesting is not the bar; load-bearing is.

### 5. Select the evidence: the fewest charts that carry the message

For each of the three supporting points, choose the minimum evidence that proves it, usually one chart or one number per point. Limit the cast of metrics; too many and the audience cannot hold the thread (juiceanalytics). Classify each headline metric as one you want to rise or one you want to fall, and present it so the direction of good is obvious.

Decision rule: aim for one clear visual per supporting point and no more than one idea per chart. If a slide or section carries two charts making two points, split it into two.

### 6. Make each chart state its own point

Hand the chart type itself to `chart-selection`, then do the storytelling work on top of it. Each chart's title is its takeaway written as a sentence, not its subject: "Onboarding over 14 days triples churn", not "Churn by onboarding time". Direct the eye to the one mark that matters using a single accent colour against grey, and run the "where are your eyes drawn?" test: look away, look back, and check your eye lands where the point is (Nussbaumer Knaflic). Strip gridlines, redundant legends, decimal noise and chart junk so only the signal remains. Annotate the key point on the chart itself, because a reader who sees the annotation gets the point without reading the surrounding text.

Decision rule: reserve saturated colour for the one thing the reader must see; everything else is neutral. If more than one colour is fighting for attention, the chart has more than one point and breaks the one-idea rule.

### 7. Write the "so what" and the ask

For every chart and every section, state the takeaway in words, the answer to "so what?" (Nussbaumer Knaflic; juiceanalytics). Use narrative guidance so the reader is never left to interpret alone: set the context, say how to read the chart, point to what to look at next, and state the insight and the action (juiceanalytics). End with an explicit ask: the decision you want, the option you recommend, and what happens if nothing is decided.

Decision rule: if a reader could finish the output and still ask "so what should we do?", the ask is missing. Add it as the last line of the body, before any appendix.

### 8. Check the story does not mislead

A persuasive story is still bound by the data. Do not truncate a bar axis to exaggerate a gap, do not use a dual axis to imply a correlation, do not cherry-pick the window that flatters the message, and do not drop the caveat that weakens it. Name the counter-argument from the inputs and answer it honestly. The same number read against last year can be a crisis or a win, so always give the comparator that makes the reading fair (susielu).

Decision rule: if removing a caveat would change the reader's decision, the caveat stays in the body, not the appendix. Hiding it is not storytelling, it is misleading.

### 9. Verify against the quality bar

Run the finished output against the quality bar below before it goes anywhere. Every item is checkable, not aspirational.

## Worked example, end to end

A data analyst is asked for "a readout of the Q3 retention analysis" for the product leadership review on Thursday. The exploratory version is the temptation: 18 slides, every cohort chart, every segment cut, in the order the analysis happened. It gets opened, scrolled, and produces no decision.

Starting from the decision instead: "Product leadership decides on Thursday whether to staff an onboarding squad, and this should move them to approve two hires." That is the audience, the decision and the action.

The governing message: "Day-30 retention fell from 62% to 54% this quarter, almost entirely among accounts that took more than 14 days to onboard, and a dedicated onboarding squad is the fastest lever we have." One sentence, one decision.

The pyramid, answer-first, three supporting points: (1) retention dropped eight points, and the drop is real, not seasonal; (2) the drop is concentrated in slow-onboarding accounts, not spread evenly; (3) onboarding time is something we control, so it is a lever, not a condition. The SCQA opener: we grew sign-ups 20% this quarter (situation), but day-30 retention fell eight points at the same time (complication), so do we invest to fix retention or keep pushing acquisition (question), and the answer is the message above.

Evidence, one chart per point: a line of day-30 retention over four quarters with the latest point annotated and this-quarter-versus-last labelled, so the drop cannot be read as noise; a bar of retention split by onboarding time, with the over-14-days bar in the one accent colour and its title reading "Onboarding over 14 days cuts day-30 retention by half"; a small table showing median onboarding time rising from 9 to 16 days, the controllable driver. Three charts, three points, each titled with its takeaway.

The so-what and the ask: each chart carries its one-line insight, and the closing line reads "Recommendation: approve two onboarding hires now; if we wait a quarter, the model projects another four-point retention loss." The caveat that one enterprise migration inflated onboarding times is stated in the body, because leaving it out would overstate the effect, with the adjusted figure shown. The deck is six slides, not eighteen, and it ends on a decision, not a chart.

## Templates you can use verbatim

**Story spec (fill this in before writing anything):**

```
Audience:            who reads this, what they know
Decision + occasion: what they decide, and when
Desired action:      what you want them to do
Governing message:   the one sentence they could repeat
Supporting points:   1. ...  2. ...  3. ...  (MECE, ranked)
Evidence per point:  the one chart or number that proves each
The ask:             the recommendation and the cost of doing nothing
Counter-argument:    what a sceptic says, and your honest answer
Medium + limit:      memo / deck / email / commentary, and its size
```

**SCQA opener (three to five sentences):**

```
Situation:   the context we agree on ...
Complication: what changed, why it matters now ...
Question:    the decision this forces ...
Answer:      [the governing message] ...
```

**Per-chart checklist:** title is the takeaway as a sentence; one idea only; one accent colour on the mark that matters; clutter stripped; key point annotated on the chart; comparator present; "so what" line written.

## Failure modes and anti-patterns

1. **The data dump.** The whole analysis is handed over in the order it was done, with no message and no cut. Spot it when the output has more than one chart per point or no clear headline. Fix: write the one governing message first, keep three supporting points, move the rest to an appendix (Minto; juiceanalytics).
2. **Burying the lede.** The conclusion arrives on the last slide after a long build-up, so a reader who stops early gets nothing. Spot it by reading only the first ten seconds' worth and asking if the point is there. Fix: lead with the answer, then support it (Minto).
3. **Topic titles instead of takeaways.** Charts titled "Revenue by region" leave the reader to find the point. Spot it when a title names a subject rather than making a claim. Fix: rewrite each title as the sentence the chart proves, and annotate the key mark (Nussbaumer Knaflic).
4. **No "so what", no ask.** The output describes what happened but never says what it means or what to do. Spot it by asking, at the end, "so what should we do?" and finding no answer. Fix: add the insight line to every section and an explicit recommendation at the close (juiceanalytics).
5. **Persuasion that crosses into distortion.** A truncated axis, a cherry-picked window or a dropped caveat makes the story look stronger than the data supports. Spot it by checking every axis starts at zero where it should, the window is the honest one, and no load-bearing caveat is hidden. Fix: present the fair comparator and keep decision-changing caveats in the body (susielu; and see the integrity rules in `chart-selection`).

## Quality bar

- The output names one audience and one decision, stated in a single sentence.
- There is one governing message, a complete sentence a reader could repeat.
- The structure is answer-first, with about three MECE supporting points ordered by importance, and an SCQA opener.
- Only evidence that advances the message is in the body; everything else is in an appendix or cut.
- There is at most one idea per chart, and each chart's title states its takeaway.
- Attention is directed with a single accent colour, clutter is removed, and the key point is annotated.
- Every section has a "so what" line, and the output ends with an explicit ask and the cost of inaction.
- No truncated or dual axes, no cherry-picked window, and no decision-changing caveat is hidden.
- The medium and length limit are respected, and sending or presenting to others waits for human confirmation.

## Data handling and safety

Reports and decks often carry personal or commercially sensitive figures: named customers, salaries, health or financial records, unreleased results. Show the aggregate the decision needs, not raw row-level personal data, and respect the access controls on the source rather than copying sensitive rows into a wider-shared file. Do not paste real customer records or credentials into prompts while drafting. Never invent a number, a benchmark, a quote or a trend to make a story land: a missing figure is stated as missing, and anything provisional or externally sourced carries a "verify before relying on this" note. Presenting, emailing or publishing to other people is an action on their behalf, so default to a draft and confirm before it goes out. When the story informs decisions about health, money, legal standing or employment, add a human-review step and state plainly that it is a decision aid, not the decision, and keep the honest caveats in view rather than smoothing them away to strengthen the narrative.

## Appendix: medium-specific notes (verify before relying on these)

- **Written report or memo:** open with the executive summary that is the answer plus the SCQA, then one section per supporting point with its heading written as an action title so the headings alone tell the story. Put method, full tables and robustness checks in an appendix.
- **Slide deck:** one message per slide, the slide title the takeaway, one chart carrying it. Use a final "recommendation and next steps" slide. Build the deck so the slide titles read in sequence as the whole argument.
- **Dashboard commentary:** a dashboard is exploratory, so the story lives in a short annotation or insight panel beside the live view, not in the chart titles, which must stay neutral for repeat viewers. Keep the narrative layer separate so it can be refreshed as the data moves (susielu). The dashboard itself is `dashboard-design`.
- **Email:** bottom line up front in the subject and first line, the three points as three short lines, the ask as the last line. Attach the detail rather than inlining it.
- **Notebook or doc:** keep the exploratory analysis and the explanatory write-up in separate sections, so the reader is not forced to walk your whole search to reach the point.

## Sources

- Barbara Minto, the Pyramid Principle and SCQA (via thinkinsights.net, "Pyramid Principle"): answer first, each level a summary of the ideas below it, group supporting points MECE and in about threes, order logically, move non-supporting detail to an appendix, and frame the opening with Situation, Complication, Question, Answer. Verified 4 November 2026.
- Cole Nussbaumer Knaflic, *Storytelling with Data* (lessons handout via resources.kanban.university, and the book): the big idea as a single complete sentence, choose a visual that makes the action easy, declutter and use contrast deliberately, focus attention and run the "where are your eyes drawn?" test, and state the takeaway in words to answer "so what" using a narrative arc. Verified 4 November 2026.
- juiceanalytics, "How to apply data storytelling to dashboards": a dashboard should be a guide for understanding rather than a collage of data points, map a three-act structure onto the data, use the four types of narrative guidance (set context, describe charts, guide the flow, highlight insights and actions), limit the cast of metrics, and classify metrics as hero or villain. Verified 4 November 2026.
- Susie Lu, "Storytelling in dashboards": the difference between explanatory and exploratory work, why the same metric drop reads as a crisis or a success depending on the comparator, keeping the narrative and annotation layer separate from dynamic data, and branching the narrative by the reader's goal. Verified 4 November 2026.
- Existing skill implementations reviewed as benchmarks: lamm-mit/scienceclaw `data-storytelling` (audience-tailored narrative generation, structured output), and nimrodfisher/data-analytics-skills storytelling and specification skills (purpose-first framing, metric hierarchy). Reviewed 4 November 2026 to confirm this skill adds deterministic structure, integrity rules and a verification bar the rivals leave out.