Reporting

reporting — the standing artifact that ships itself

A report is a push artifact: a fixed snapshot that lands in someone's inbox or shared drive on a cadence, the same shape every period, with no human assembling it. That is the whole job. If a human opens a live view to slice numbers themselves, that is pull — a dashboard, not a report. Hold that line; almost every failed "reporting" project is a dashboard wearing a report's name, or a report nobody can trust because the numbers went stale and no one noticed.

Your deliverable is a runnable pipeline, not advice: a template, a generation script, a schedule, and a delivery step, with a freshness gate so it fails loud instead of shipping yesterday's numbers.

Step 0 — Write the report contract (no contract, no build)

Before any code, pin six fields. An undefined audience is a report no one reads; an undefined source is a number no one can defend.

Rule: you consume an agreed metric set — you do not adjudicate which KPIs matter. If the ask is "which metrics should we even track?", that is kpi-framework, not this skill. The contract names the source and its owner so a wrong number has an address.

Decide: push report vs live dashboard (this branches — settle it first)

Audiences want a citable snapshot for the period more often than a live feed — that is why push wins for exec summaries, weekly reviews, and finance close packs.

When both are wanted, build the report and let it link to the dashboard as a "go deeper" footer.

Pick the artifact format

A board pack is a PDF; an analyst hand-off is a spreadsheet. Picking PDF for analysts who wanted to pivot is the most common format miss.

The four-layer pipeline: fetch → narrate → render → deliver

Keep the four layers separate so each is testable and the template never knows where data came from.

Pinned stack (Python, the most-documented 2025 PDF path — verified on PyPI 2026-06-02): pandas (data) → Jinja2 (HTML template) → WeasyPrint 68.1 (HTML+CSS → PDF), Matplotlib for embedded charts. Pin WeasyPrint — major versions change CSS support, so an unpinned bump can silently reflow a board pack. Re-check PyPI before you freeze, then freeze what you resolve.

# render.py — minimal fetch → narrate → render. Delivery + charts live in references/pipeline.md.
import pandas as pd
from jinja2 import Environment, FileSystemLoader
from weasyprint import HTML  # WeasyPrint==68.1

def build_report(metrics_csv: str, params: dict) -> bytes:
    df = pd.read_csv(metrics_csv)                      # fetch
    df = df[df["region"] == params["region"]]          # per-recipient scope, NOT a new template
    cur, prev = df["revenue"].iloc[-1], df["revenue"].iloc[-2]
    ctx = {
        "title": f'{params["region"]} weekly revenue',
        "period": params["period"],
        "summary": narrate(cur, prev),                 # narrate (see below)
        "rows": df.tail(8).to_dict("records"),
    }
    env = Environment(loader=FileSystemLoader("templates"))
    html = env.get_template("report.html.j2").render(**ctx)   # render
    return HTML(string=html).write_pdf()

Rule: one template, per-recipient params — regional managers each get their region from the same report.html.j2, scoped by params, never a forked template per recipient. A template-per-recipient codebase rots the first time the layout changes. The full worked template, the Matplotlib base64 chart embed, the per-recipient loop, the GitHub Actions workflow, and the freshness gate are in references/pipeline.md.

The narrative layer (the part that gets read)

Executives read the executive summary and stop. Lead every report with: the report's purpose in one line, 3 key takeaways, and what changed versus last period. Then per section, one period-over-period delta sentence and one "so what". An annotated chart callout is retained; a bare chart is not.

def narrate(cur: float, prev: float) -> str:
    delta = (cur - prev) / prev * 100
    arrow = "up" if delta >= 0 else "down"
    flag = " — investigate" if abs(delta) >= 20 else ""    # anomaly callout
    return (f"Revenue {arrow} {abs(delta):.1f}% vs last week "
            f"(€{cur:,.0f} from €{prev:,.0f}){flag}.")

Bad → Good, the difference that decides whether the report is useful:

• Bad: a table row Revenue | 248,300 | 201,400. The reader must do the math and guess if it matters.
• Good: "Revenue up 23.3% WoW (€248,300 from €201,400) — investigate: driven by the enterprise renewal that won't recur next week."

The numbers are the evidence; the sentence is the report.

Schedule + reliability gate (where reports actually die)

Reports die two ways: stale data ships silently, and a silent break means no one notices for weeks. Treat the schedule as managed infrastructure.

Where to run it:

This skill owns the report-shaped concern (contract, narrative, artifact) and uses a scheduler — it does not teach scheduling in general. The actual transport (SMTP/Gmail send) belongs to email-connector; for a Drive/Workspace destination see google-workspace. The GH Actions schedule: YAML is in references/pipeline.md.

Reliability checklist — every recurring report:

• Freshness gate before send — assert the source is newer than the last period; if stale, do NOT send, raise instead. A report that consumes dirty data is not this skill's job to clean — that is data-cleaning; this gate only refuses to ship known-stale numbers.
• Fail loud — on any error, alert the owner (the report not arriving is itself a silent failure).
• Idempotent run — re-running for the same period produces the same artifact, no duplicate send.
• Dead-report cleanup — if no one opened the last N editions, kill the schedule. Unread reports are pure cost and noise.

Anti-patterns

Verify

Run scripts/verify.sh (read-only; pass a path to a generated pipeline directory, or run in it). It confirms a Jinja2 template renders against a sample context without error, the generation script produces a non-empty PDF/HTML artifact, a schedule definition exists (a crontab line or a .github/workflows/*.yml with a schedule: block), and a delivery step is wired. It soft-warns if no freshness/failure gate is detected, and exits 0 on an empty/clean target — nothing to check is not a failure.