data-to-deck

name	data-to-deck
description	Turn a CSV/Excel export into a HubSpot-branded executive dashboard, slide deck, or one-pager. Use when someone wants a data file made into a deck, dashboard (interactive HTML, spreadsheet, or BI platform), KPI view, or charts. Applies HubSpot's brand, metric definitions, and Flywheel voice; derives the metrics that matter and reports them the way HubSpot reports them.
version	2.0.0
tags	["hubspot","data","dashboard","deck","presentation","one-pager","visualization","executive-reporting"]
keywords	["data to deck","build a dashboard","make a slide deck","KPI view","executive summary","HubSpot report","brand a chart"]

Data to Deck

Transform a raw data export into a focused, HubSpot-branded executive artifact: decide what deserves to be shown, engineer the metrics that aren't already columns, and leave out the rest. The artifact must answer "so what?" in under a minute and look like HubSpot made it.

HubSpot house style — apply to every artifact

Full reference in references/hubspot_context.md. In brief:

• Brand: orange #FF7A59 primary, navy #33475B ink, #516F90 muted, teal #00A4BD / green #00BDA5 accents. Font Lato (fall back to Arial for Office QA reliability). Sprocket mark in the header. Flywheel motif (Attract → Engage → Delight).
• Voice & framing: the Flywheel. Customer-feedback and health readouts are a Delight-stage story. Tie findings to HubSpot's reported operating metrics (Net Revenue Retention, churn, customer count) so the artifact reads as an internal document.
• Metric definitions — use these, they are HubSpot's:
  • NPS = %(9–10) − %(0–6) on completed responses (not the mean of the score).
  • Delighted = CSAT ≥ 9 of 10, top-2-box (not the average).
  • Ease-of-use = share rating 4–5 of 5.
  • Conversion rate = orders ÷ sessions. Checkout→order = orders ÷ checkouts started.
  • AOV = revenue ÷ orders. ROAS = revenue ÷ ad spend (blended). CTR = clicks ÷ impressions (paid channels only).
• Data hygiene: region code "NA" = North America (the largest region), not missing.
• Good/bad still overrides brand: a red bar for a negative NPS even though red isn't a brand color.

Every number ships with its definition (footer/appendix) so it's reproducible. Use the same definition across every format so a figure never changes between the deck, dashboard, sheet, and one-pager.

When to use

• Someone hands you a CSV/Excel export (or points at one) and wants a deck, dashboard, one-pager, or "some charts."
• An existing report is a generic chart dump and needs a point of view and HubSpot branding.
• Someone wants the same analysis in several formats (deck and dashboard and a one-pager) that agree with each other.

When NOT to use

• Building one chart from data you already have in memory → just make the chart.
• Writing SQL / building the data pipeline → that's upstream of this skill.
• A pure narrative doc with no data → use the docx skill directly.
• Designing a live BI workbook you can't build here → this skill ships a dataset + measure spec instead (Phase 4A-BI).

Quick reference

Decision	Rule
Branding	Apply the HubSpot house style (colors, Lato/Arial, sprocket, Flywheel voice) to every artifact. A chart-library default look is wrong.
Definitions	Use HubSpot's definitions (above): NPS on completed responses, Delighted = CSAT ≥ 9, Conversion = orders ÷ sessions, etc. Ship each definition in the footer.
Output family	Dashboard (monitor repeatedly) · Deck (present once) · One-pager (read/email). Default to a deck if unsure; offer the others.
KPI count	Dashboard: 4–6 headline KPIs. Deck: 3–7 metric slides. If everything is important, nothing is.
Metric worth showing	Only if a decision-maker could act differently on its value. Drop vanity, identifier, near-constant, high-null columns.
The finding	Write the artifact's headline in one sentence with a number in it. If you can't, Phase 3 isn't done.
Chart choice	From the metric's structure, not habit. Default: sorted horizontal bar.
Titles	State the finding ("Mobile converts at half of desktop"), not the label ("Conversion by device").
Numbers	Compute in code / live formulas. Same definition → same number across every format, to the digit.
Color	HubSpot brand for series; green/red only for good/bad vs a target. Guard zero denominators (—, not 0.00x).
Deck style	Working deck by default (exec summary → finding slides). Big-number statement slides only for the 1–2 key moments.
Chart tech	Dashboards: React+Recharts for a Claude artifact (gradient area, tooltips, shadowed cards), else self-contained inline-SVG HTML (no CDN). Sheets: live formulas, zero recalc errors, print areas set.
Look finished	KPIs in cards (not floating text) · numbers on one line · no underline under titles · exact HubSpot palette · no NaN/$NaN.

Choose the output first

Ask (or infer from the request) which artifact fits:

• Dashboard — a view someone returns to repeatedly to monitor KPIs. "Dashboard" is a family, not one format — pin which build target is meant before building (details in references/dashboard_formats.md):
  • Interactive HTML — self-serve, explorable, opens in a browser. The default when someone just says "dashboard." → Phase 4A-HTML.
  • Spreadsheet (Excel/CSV) — formula-driven KPIs + native charts they can pivot, trace, and edit. Choose when they say "in Excel," "spreadsheet," "with the underlying data," or need to audit numbers back to source. → Phase 4A-Sheet.
  • BI platform (Tableau / Power BI / Looker) — you can't build the live workbook, so ship a clean modeled dataset + a field/measure spec they import. Choose when they name a BI tool. → Phase 4A-BI. Family triggers: "dashboard," "KPI view," "monitor," "track," or wanting something live/explorable.
• Deck — a linear, narrated PowerPoint for a one-time readout to an audience. Choose when they say "deck," "slides," "present," "readout," "for leadership." → Phase 4B.
• One-pager — a one-page summary to read or hand off. A written docx/markdown when it's mostly prose, or a designed single-page PDF (branded header, KPI row, the one headline finding, a small supporting table/chart) when it should look like a polished exec snapshot. Choose when they want something to read or email, not present. → Phase 4C.

If ambiguous on the family, default to a deck and offer the others. If ambiguous on dashboard format, default to interactive HTML. People often want both a deck and a dashboard — if the request implies both, build both from the same Phase 0–3 analysis.

Workflow

Follow these phases in order. Do not skip Phase 0 or profiling — every downstream choice depends on them.

Phase 0 — Apply HubSpot context

Load the HubSpot house style above (full detail in references/hubspot_context.md): brand, the Flywheel voice, and HubSpot's metric definitions. These are fixed — do not re-derive them per request. Everything downstream — which metrics you engineer, how you define them, how you color and title charts — inherits from this context. If the data uses a term HubSpot defines specifically (CSAT, NPS, active, churn), use HubSpot's definition, not a generic one.

Phase 1 — Profile the data

First run scripts/clean_load.py <file> --out clean.csv to coerce $/comma/% columns to real numbers (prevents $NaN in ROAS/AOV), resolve coded values (NA→North America), and flag constant/id/high-null columns. Then run scripts/profile_data.py clean.csv for a structured profile: column names, inferred semantic type (categorical / ordinal / numeric / temporal / free-text / identifier), cardinality, null rate, and distribution stats. Read the JSON it prints. Do NOT eyeball the raw CSV and guess — compute from the cleaned file.

Phase 2 — Engineer metrics

The most important metrics are usually not raw columns — they are derived. From the profile, construct the metrics the data only implies. Use references/metric_engineering.md for the catalog of derivations. Common moves:

• Rates from raw counts: completion %, conversion %, % Delighted (CSAT ≥ 9), churn rate. A "completed" 0/1 column becomes a completion rate; a 1–10 CSAT column becomes "% Delighted (≥ 9)."
• Composite indices: NPS from a 0–10 recommend column (promoters 9–10 minus detractors 0–6); a health score blending several inputs.
• Segmented cuts: any rate broken down by a categorical dimension (Delight by segment, conversion by channel). The breakdown is usually where the story lives, not the aggregate.
• Movement: period-over-period change, trend slope, this-vs-last comparison.
• Concentration / distribution: top-N share, Pareto, outlier flags.
• Free-text → themes: cluster open-ended responses into 3–5 named themes with counts.

Record each derived metric with its definition and compute it HubSpot's way (Delighted = CSAT ≥ 9, not ≥ 8). Definitions go in the artifact so numbers are reproducible.

Resolve coded values before you compute: region "NA" = North America, not null — a naive parser silently drops it and loses the largest segment. Fix these mappings first; note them in the footer.

Phase 3 — Select what to surface

You will usually have more candidate metrics than you should show. Use references/metric_selection.md. Core test: a metric earns space only if a decision-maker could act differently depending on its value. Targets:

• Dashboard: 4–6 headline KPIs as scorecards, then 3–6 supporting charts.
• Deck: 3–7 metric slides.

Demote or drop identifier columns, near-constant columns, high-null columns, and interesting-but-not-actionable metrics. Keep a short list of what you dropped and why; put it in the appendix/footer.

End Phase 3 by writing the headline. One sentence, with a number: "Mobile is 62% of traffic but a third of the orders." Everything you build serves that sentence. If you can't write it, you're not done selecting.

Phase 4 — Map each metric to a visualization

Use references/chart_selection.md. Pick the chart from the metric's structure, not from habit:

• Single number that matters → big-number scorecard (no chart)
• Ranking of categories → sorted horizontal bar
• Parts of a whole, >3 parts → ranked bar (not pie)
• Distribution of one numeric → histogram
• Change over time → line
• Two numerics → scatter
• Likert / rating scale → diverging stacked bar
• Stage-to-stage drop-off → funnel (bars scaled to volume, with step-conversion %) When unsure, default to a sorted horizontal bar — hardest to mislead with, easiest to read in 3 seconds.

Then build the chosen artifact:

Phase 4A — Dashboard

Pick the build target from "Choose the output first" and read references/dashboard_formats.md (covers all three). In every case: apply the HubSpot brand, put the metric definitions in a footer/notes area, title each chart with its finding, and show values on the bars (don't force the reader to hover).

Phase 4A-Interactive — HTML or React. Read references/dashboard_build.md. It has two build modes; pick by where the dashboard will be viewed:

• React + Recharts — when it will be a Claude artifact or live in a React app. The richest, most polished result: soft-shadow KPI cards with a left accent + delta, a gradient area trend chart, hover tooltips, and segmented/dropdown filters that recompute via useMemo. HubSpot-branded (orange/navy), never generic slate/violet.
• Self-contained HTML (default) — when it must open anywhere, embed, or render in a sandboxed preview (Cowork, chat file-preview). No CDN <script> (renders blank there); hand-build inline SVG, pre-rendered so it shows with scripts off, plus vanilla JS for filters and hover tooltips. Match the React look (shadowed cards, gradient area, tooltips) with plain web tech. No localStorage.

Either way: 4–6 KPI cards with deltas, a finding-titled chart grid, definitions footer, and no NaN/$NaN anywhere (guard divide-by-zero; parse numeric columns so a missing ad_spend never becomes "$NaN ROAS").

Phase 4A-Sheet — Spreadsheet (Excel). Read the xlsx skill. Put raw rows on a Data sheet and build a Scorecard/Dashboard sheet whose KPI cells and every segment/region/trend cut are live formulas (SUMIFS/COUNTIFS/AVERAGEIFS referencing Data), not numbers hardcoded from Python — so they can trace and re-run them. Add native Excel charts (per-point colors for good/bad). Brand the header row and KPI cards in HubSpot colors. Set each sheet to landscape, fit-to-width, with a print area so the workbook exports to a tidy one-page-per-tab PDF. Recalculate with the xlsx skill's recalc.py and confirm zero formula errors before delivering.

Phase 4A-BI — BI platform (Tableau / Power BI / Looker). You can't build the live workbook, so ship what an analyst drops straight in: (1) a clean, tidy, analysis-ready dataset — one row per observation, typed columns, coded values resolved ("NA"→North America); (2) a measure/field spec listing each KPI with its HubSpot definition and the calculated-field formula in that tool's language (Tableau calc, Power BI DAX, LookML); (3) a suggested tile layout — scorecards plus which dimension each chart breaks by. Deliver as a CSV + a markdown spec.

Phase 4B — Deck (PowerPoint)

Read the pptx skill (/mnt/skills/public/pptx/SKILL.md where present), the content skeleton in references/deck_structures.md (readout/QBR, investor, sales, board), and references/deck_build.md for the slide-by-slide visual recipes — follow them, they are what separate a finished deck from an AI-looking one. The rules that most often get missed:

• Title slide: dark navy, a kicker + a clean mark (a solid orange gear/sprocket or a plain solid dot — never a ring, white center, or concentric circles, which read as a bullseye/target), a big title, a readable subtitle in ice/white (not muted navy on navy), and a bottom metadata strip of 3–4 labeled facts (Period · Storefront · N · Revenue). The meta strip is what makes it look designed.
• Scorecard: KPIs in cards, not floating text, vertically centered — numbers on one line ($7.26M, never wrapped).
• Every slide fills the frame — no large empty lower half; anchor it with a meta strip, an insight callout, or a bigger chart.
• No underline under any title. Format chart axes/labels ($500K, $1.0M, 3.1%), not raw 500000. Exact HubSpot palette, high contrast on dark slides.

Prefer native, editable PowerPoint charts over image charts. Bars must be strictly proportional (a half-value bar is half as long — no minimum-width padding) with value labels beside the bar, and nothing may overflow a card/slide edge (reserve a right gutter for the biggest bar's label).

Easiest correct charts: use scripts/funnel_chart.py (funnels — centred stages with tapered shoulders, so it reads as a funnel) and scripts/chart.py (barh/group/line) — they emit proportional, non-overflowing, branded PNGs you insert as images, removing the whole class of bar bugs. Pass no --title when the slide already shows the headline: the chart image would repeat it in a second size, which is a defect.

Mandatory finish step: run scripts/check_deck.py deck.pptx (deterministic — flags off-slide overflow and NaN/placeholder tokens), then render the deck to images and fix every issue — overflow, wrapped numbers, disproportionate bars, title underlines, low contrast, empty quadrants — before returning it. This gate is the main reason a generated deck reaches hand-built quality; do not skip it.

Pick the deck style to match the setting, and say which you're building:

• Working deck (default — QBR, readout, board pack): an executive-summary slide, then denser chart slides that each state a finding, then recommendations. This is what teams present internally.
• Keynote (a live stage, persuasion — INBOUND, an all-hands): one idea per slide, bold statement slides, minimal text. Reserve big-number statement slides for the one or two moments that carry the story (the headline finding, the opportunity) — not every slide. A big number on every slide reads as a keynote and buries the analysis.

Phase 4C — One-pager

Two builds, depending on whether it should read like a memo or look like a snapshot:

• Prose (docx/markdown) — read the docx skill (or write markdown). Lead with the executive summary, then the 3–4 most decision-relevant findings as short prose with small inline charts.
• Designed PDF — a single landscape page: a HubSpot-branded header, a KPI scorecard row, the one headline finding called out with its number, and one supporting element (a small comparison table or a mini funnel/bar), with the metric definitions in the footer. Build it with reportlab (draw to a fixed-size canvas) for layout control — not by exporting a Word doc. Keep every figure identical to the deck/dashboard/spreadsheet.

Phase 5 — Write the narrative

Lead every artifact with an executive summary: 3–5 plain-language takeaways ("Delight is 79% for Enterprise but 23% for SMB; the flat headline NPS hides this split"). Each chart gets a one-sentence insight as its title or subtitle, phrased in the Flywheel voice. Close with "what to do next" if the data supports recommendations. Never let a chart sit without a stated finding.

Deck skeleton (Phase 4B)

1. Title — what this is, data source, date range, N
2. Executive summary — 3–5 takeaway bullets
3. Headline scorecards — the 3–4 KPIs as big numbers
4. 3–7 metric slides — one chart each, finding as the title
5. Recommendations / open questions — only if warranted
6. Appendix — metric definitions + what was dropped and why

Dashboard layout (Phase 4A — HTML variant; see references/dashboard_formats.md for spreadsheet & BI)

1. Header — title, data source, date range, N
2. KPI scorecard row — 4–6 big numbers, each with label + delta
3. Chart grid — 3–6 supporting charts, finding-titled, responsive
4. Footer — metric definitions + dropped-columns note

Worked examples

Full end-to-end walk-throughs — from raw export to finished artifact, with layout mockups, the metrics kept vs dropped, color logic, and the one finding each is built around — are in references/worked_examples.md. It covers:

1. Ecommerce funnel → HubSpot working deck (the mobile-checkout leak, ~$1.93M recoverable).
2. The same funnel → interactive HTML dashboard (filter by device/channel).
3. The same funnel → one-page PDF exec snapshot.
4. Customer survey → HubSpot Delight readout (flat NPS hides an Enterprise +45 / SMB −30 split).
5. Skill off vs skill on — the same prompt, generic vs HubSpot-branded and finding-first.

Condensed shape of a finished one — an ecommerce funnel as a HubSpot working deck:

Context   HubSpot: orange #FF7A59 / navy #33475B / sprocket; Conversion = orders÷sessions
Finding   "Mobile is 62% of traffic but a third of the orders" (checkout→order 36.6% vs 68.9%)
Deck      Title · Exec summary · Scorecard(6) · Trend · Channels · Funnel ·
          THE finding (device split) · Opportunity ~$1.93M (the one big-number slide) ·
          Recommendations · Appendix(definitions)
Color     orange=primary, navy=ink, red=mobile gap(bad), green=desktop(good)

Pre-ship checklist

Before delivering, verify:

• HubSpot house style is visible — brand colors, sprocket, Flywheel voice, and HubSpot's metric definitions in the footer. It should read as an internal HubSpot document.
• The headline exists — one sentence with a number, on the exec-summary slide / finding band.
• Every chart states a finding in its title, not just the metric name — and states it once (no chart image repeating the slide headline).
• Every number is computed in code or live formulas, and agrees to the digit across all formats you shipped (deck = dashboard = PDF = sheet).
• Definitions ship with the artifact; N and date range are stated.
• ≤ 6 KPIs / ≤ 7 metric slides; dropped-columns note in the appendix/footer.
• Zero-denominator ratios show —, not a misleading 0.00x / 0.0%.
• Looks finished: KPIs are in cards (not floating text), no number wraps, no underline under any title, palette is HubSpot navy/orange, and there is no NaN/$NaN anywhere.
• Deterministic gate passed: scripts/check_deck.py reports OK (no overflow, no bad tokens) on the finished deck; charts built with the helper scripts or verified proportional by hand.
• Format-specific: React dashboards use the branded Recharts look (gradient area, tooltips, shadowed cards); self-contained HTML has no CDN dependency and renders in a preview pane; spreadsheets pass recalc.py with zero errors and have print areas set; decks pass the pptx validator and have been eyeballed (rendered to images) for overflow, underlines, and wrapped numbers.
• Numbers formatted for humans — $7.26M, not ; , not .

Common mistakes

• Off-brand output — charts that look like a chart-library default instead of HubSpot. Root cause: the house style wasn't applied.
• Wrong definition — computing CSAT as a mean instead of % Delighted (≥ 9), or NPS off the mean of the score.
• Chart dump with no headline — a grid of charts and no stated "so what?".
• The headline printed twice — the slide title and the chart image's own title, in two sizes. State it once; the chart image goes titleless under a slide headline.
• A funnel that's just left-aligned bars — centre the stages and taper between them, or it isn't reading as a funnel.
• Labels crowding each other — a legend touching the axis labels, a drop-off % set in unreadable fine print.
• Vanity metrics — impressions, registered users, followers: shown because they're in a column, not because anyone can act on them.
• Numbers that disagree across formats — the deck says 3.1% and the sheet says 3.09% because one was typed and one was computed. Compute once; reuse.
• A big number on every slide — that's a keynote; a working deck earns its big numbers.
• Coded values dropped — treating region "NA" as null and silently losing the largest segment.
• CDN charts in a dashboard — render blank in sandboxed previews and offline.
• Truncated axes / pies with >3 slices / dual y-axes — three fast ways to mislead.

Tips & tricks

• Run the 5-second test: show the artifact to someone for five seconds, then ask "what's the one thing?" If they can't answer, the hierarchy (or the headline) isn't clear.
• Grey is your default; color is a highlight. Use HubSpot orange only on the series that carries the finding; everything else is context.
• Lead with the segment split, not the average. The aggregate is usually flat; the story is in the breakdown (by segment, channel, device).
• Tie the finding to a reported metric. A negative-NPS segment is the leading indicator of churn and NRR — say so; that framing makes it read as HubSpot's.
• Build one format fully, then fan out. Lock the analysis (Phase 0–3), build the deck, then the dashboard/PDF/sheet reuse the same computed numbers — never recompute per format.

Guardrails

• Brand and define like HubSpot. Apply the house style and HubSpot's metric definitions to everything. An artifact that looks like a chart-library default, or that computes a metric a non-HubSpot way, is wrong.
• Resolve coded/ambiguous values before analysis (region "NA" is North America, not missing). A naive parser that treats them as null loses real data — often the largest segment.
• Never show more than ~6 KPIs or ~7 metric slides. If everything is important, nothing is.
• Every derived metric ships with its definition so numbers are reproducible. Keep the same definition across every artifact (deck, HTML, spreadsheet, PDF) so a number never changes between formats — watch rounding of exact half-values.
• Never use a pie chart for >3 slices, never use dual y-axes, never truncate a bar-chart axis to exaggerate difference.
• Guard zero denominators. When a rate has no base — ROAS for an unpaid channel, conversion for a segment with no sessions — show — (or n/a), never a misleading 0.00x or 0.0% that reads as real underperformance.
• Never ship NaN, undefined, or $NaN. Parse numeric columns before computing and guard every division; a missing ad_spend must not surface as "$NaN ROAS." Scan the finished output for these tokens before delivering.
• Look finished, not AI-generated. KPIs go in cards, not as floating text; big numbers stay on one line; never underline a title; keep the exact HubSpot palette (don't drift to slate). Render decks to images and dashboards in a preview, and fix overflow/underlines/wrapped-numbers before shipping.
• Bars proportional, nothing overflowing. Bar length is strictly linear to the value (no minimum-width padding that makes 172K and 334K look equal); value labels sit beside bars; reserve a right gutter so the biggest bar and its label never cross a card/slide edge.
• Render-and-fix is a gate. For any deck or dashboard, render the finished file to images (or a preview) and fix every visual defect before returning it — this is what closes the gap to hand-built quality.
• Always state N and date range so numbers are interpretable; flag small or skewed samples.
• Compute aggregates in code (a script or live spreadsheet formulas), not by eyeballing — arithmetic stays deterministic.
• Don't invent causation. "X rose" is a finding; "X rose because Y" needs evidence.
• Surface your metric selection so the requester can re-rank; this is a drafting accelerator with an audit trail, not an oracle.

References

• references/hubspot_context.md — the HubSpot brand, voice, and metric definitions applied in Phase 0.
• references/metric_engineering.md — catalog of derivations (rates, indices, cuts, movement, themes).
• references/metric_selection.md — the "does this earn space?" test.
• references/chart_selection.md — metric structure → chart type.
• references/dashboard_formats.md — the three dashboard build targets (HTML / spreadsheet / BI).
• references/dashboard_build.md — the self-contained HTML build guide.
• references/deck_structures.md — slide skeletons by purpose (readout/QBR, investor, sales, board) + headline rules.
• references/deck_build.md — deck visual rigor (KPI cards, no title underlines, number formatting, contrast, palette).
• references/worked_examples.md — five full end-to-end examples with layout mockups.
• scripts/profile_data.py — Phase 1 data profiler. scripts/make_charts.py — chart helpers.
• scripts/funnel_chart.py — draws a correctly-proportioned, non-overflowing funnel PNG that actually looks like a funnel (centred stages, tapered shoulders, legible step-to-step drop %). Use it for any funnel instead of hand-drawing bars.
• scripts/chart.py — the same guarantee for barh (ranked bars, one accent bar + navy context), group (clustered columns with the legend on its own row), and line/area charts (labelled gridlines, endpoint values): linear sizing, labels outside, reserved gutters, formatted values, HubSpot palette. Use for the channel ranking, the device split, and the revenue trend.
• scripts/check_deck.py — deterministic pre-ship gate: flags any shape that overflows a slide edge and scans text for NaN/$NaN/#DIV/0!/placeholders. Run it on the finished .pptx (works on .html/.xlsx for the token scan too); fix what it names, re-render, re-run until clean.
• scripts/clean_load.py — robust CSV/Excel loader: coerces $/comma/% columns to real numbers (so ROAS never renders $NaN), resolves coded values (NA→North America), and flags constant/id/high-null columns to drop. Load through this before computing.