Report Builder

---
name: report-builder
description: Use when generating a multi-section data report PDF — KPI report, business review, research findings, post-mortem. Triggers on "build a report PDF", "monthly business review", "research report".
---

# Report Builder

Generate a multi-section report that's readable on screen and survives being printed. Reports fail when charts come out blurry, tables overflow page edges, or readers can't tell which section they're in. Get those three right.

## Required inputs

1. **Report title + reporting period**
2. **Audience** — exec / board / team / external — calibrates length and tone
3. **Sections** — at minimum: TL;DR, key metrics, deep dives, what's next
4. **Data** — tables (CSV-able), chart specs (or pre-rendered images), narrative bullets
5. **Branding** — logo + accent color + (optional) watermark for confidentiality

Push back if the user gives you raw data without an interpretation: "What's the story this report tells?" A report without a thesis is just a data dump.

## Approach

**Best**: HTML + print CSS via headless Chrome (puppeteer / playwright). Charts rendered as inline SVG (D3, Chart.js exported, or Vega-Lite) — they scale crisp at any DPI.

**Python-heavy environments**: matplotlib or plotly figures saved as SVG/high-DPI PNG, embedded into a Jinja-templated HTML, then WeasyPrint to PDF. Or use Quarto/Pandoc for a single-pipeline approach.

**LaTeX**: appropriate for academic or research-formal output. `article` or `scrartcl` class, `booktabs` for tables, `pgfplots` for charts. More work but typesetting is unmatched.

Avoid: screenshotting charts from a dashboard. They pixelate, the legend cuts off, and the timestamp gives away that the report is stale.

## Structure

1. **Cover page** — title, period, prepared by, date, "Confidential" if relevant
2. **Table of contents** — auto-generated, only if 8+ pages
3. **Executive summary** (1 page) — 3-5 bullets, biggest numbers, biggest risks
4. **Section per topic** — each starts with a section header on its own line, then narrative + chart/table
5. **Appendix** — methodology, definitions, raw data tables if needed

Each section: 1-paragraph narrative ABOVE the chart/table (the answer), then the supporting visual. Don't make the reader puzzle out the chart first.

## Style guidance

- Page size: A4, US Letter for US audiences. Be consistent.
- Margins: 20mm all around; 25mm if the report is bound
- Body type: 10-11pt sans-serif (Inter, Source Sans, Helvetica). Tables can drop to 9pt.
- Headers: same font family, weight changes only — no decorative fonts mid-report
- Charts: 1 chart per concept. Title in 11pt above; source line in 8pt below.
- Tables: `booktabs` style — top rule, mid rule, bottom rule. No vertical lines. No zebra striping unless rows > 15.
- Page header: report title (left), section name (right). Page footer: page X of Y, "Generated [date]".

## Common pitfalls

- **Blurry charts**: never use raster screenshots. SVG or 300dpi PNG minimum.
- **Tables overflow page width**: shrink type, rotate to landscape for that page, or split the table.
- **Inconsistent date formats** between sections (Jan 2026 vs 01/2026 vs 2026-01) — pick one and lint.
- **No page break between sections**: jarring. Use `page-break-before: always` per section.
- **Missing data labels on charts**: a chart without a Y-axis label or units is useless in print.
- **Confidentiality leak**: if it's confidential, watermark every page diagonally at 12% opacity. PDF metadata also matters — set `/Title` and remove author info.

## Output

Generate the PDF, then summarize: page count, section count, charts/tables included, any data gaps you flagged. If the user asked for "charts" without specifying which, list what you generated and offer to swap.