monthly-performance-summary

Monthly performance summary

Generate a plain-language performance summary from Planable analytics data or a CSV export. Works in two modes: connected (pulls data live via Planable) or CSV (user uploads their own export).

---

Step 0: Detect the input mode

Mode A — Planable connector (default) The user has a Planable account connected and wants to pull live data.

Mode B — CSV upload The user has uploaded (or will upload) a CSV export from Planable or any social media analytics tool.

How to detect:

• If the user uploads a file → Mode B
• If the user mentions "export", "CSV", "spreadsheet", or "file" → Mode B
• If the user mentions a workspace name, client, or Planable directly → Mode A
• If unclear, ask: "Do you have a CSV export to upload, or should I pull the data from your Planable workspace?"

---

Mode A: Planable connector

Step 1: Gather inputs

• Workspace / client name — which workspace to report on
• Date range — default to previous calendar month if not specified
• Platforms to include — all pages by default, or specific platforms if requested

Step 2: Fetch data

list_workspaces → find workspaceId
list_pages(workspaceId) → get all pageIds
get_page_metrics(workspaceId, pageIds, startDate, endDate)
get_page_metrics_summary(workspaceId, pageIds, startDate, endDate)
get_post_metrics_summary(workspaceId, pageIds, startDate, endDate)

For top post highlights, also call:

get_post_metrics(workspaceId, pageIds, startDate, endDate, limit: 5)

Note on unsupported platforms: get_page_metrics returns unsupportedPages for Google My Business and Threads — note these in the report as "data not available."

Step 3: Structure the report → go to Report Format

---

Mode B: CSV upload

Step 1: Accept the file

If no file is uploaded yet, ask: "Please upload your CSV export and I'll summarize it."

Supported sources: Planable Analytics export, Hootsuite, Sprout Social, Meta Business Suite, LinkedIn Analytics, or any tabular CSV with date, platform, and metric columns.

Step 2: Parse the CSV

Read the uploaded file. Identify:

• Date column — look for date, period, week, month, or similar
• Platform column — look for platform, channel, network, page, profile
• Metric columns — impressions, reach, views, engagement, likes, comments, shares, followers, engagement rate

If the structure is unclear or columns are ambiguous, ask one clarifying question before proceeding.

Flexible parsing rules:

• Column names may vary by source — match by keyword, not exact name
• Aggregate by platform if data is at post level
• Handle blank rows and footer rows gracefully (skip non-numeric rows in metric columns)
• If a date range is not obvious from the data, ask the user to confirm what period the export covers

Step 3: Structure the report → go to Report Format

---

Report Format

Deliver the report as a downloadable HTML file — a self-contained visual report the user can open in a browser, share with a client, or screenshot. Also output a short plain-text summary in chat so the user can see the key numbers without opening the file.

---

Visual HTML report

Generate a single .html file saved to /mnt/user-data/outputs/[client-name]-[month]-report.html. Use present_files after creating it.

The report must be visually designed — not a raw data dump. Follow these design principles:

Aesthetic direction: Clean, modern agency report. Light background, bold accent color (use Planable green #3BBA7B as primary accent). Card-based layout. Generous whitespace. Clear hierarchy.

Required sections and visual treatment:

1. Header

• Client name (large)
• Month + year
• Tagline: "Social Media Performance Report"
• Subtle gradient bar or divider in Planable green

2. 📊 Headline numbers — KPI cards

4 metric cards in a row (or 2×2 on narrow):

• 👥 Total audience (followers across all platforms)
• 👀 Total impressions
• 💬 Total engagement
• 📅 Posts published

Each card: big bold number, label, and trend arrow + % change vs. prior period (if available). Use color: green for up ↑, red for down ↓, gray for flat.

3. 📱 Platform breakdown

One card per platform. Each card shows:

• Platform emoji + name (use: 📘 Facebook, 📸 Instagram, 💼 LinkedIn, 🐦 X/Twitter, 🎵 TikTok, ▶️ YouTube, 📌 Pinterest)
• Audience / followers
• Impressions
• Engagement rate (shown as a mini visual bar, CSS only — width = engagement rate %, max 100%)
• Posts published
• One-line notable (italic, lighter text)

4. 🏆 Top posts

Up to 5 posts in a ranked list. Each entry:

• Rank badge (1st, 2nd, 3rd...)
• Platform emoji
• Post text preview (truncated to ~120 chars, in quotes)
• Key metric pill (e.g. "847 engagements" or "12K impressions") — styled as a badge

5. ✅ What worked / ⚠️ What to watch

Two columns side by side:

• Left: "✅ What worked" — 2–3 bullet points in green
• Right: "⚠️ What to watch" — 1–2 bullet points in amber/yellow

Keep bullets short and specific. No generic advice.

6. 📝 Notes

Small, muted section at the bottom. Flag data gaps, unsupported platforms, report freshness.

7. Footer

"Generated with Planable + Claude · [date]"

---

HTML/CSS requirements

• Single self-contained .html file — no external dependencies except Google Fonts (loaded via <link>)
• Use a distinctive font: DM Sans or Plus Jakarta Sans for body, Sora or Bricolage Grotesque for headings
• CSS variables for all colors — define at :root
• Responsive: works at 900px+ desktop width; cards wrap gracefully on smaller screens
• No JS required — pure HTML/CSS
• Print-friendly: @media print block that hides nothing essential
• Use real data from the report — no placeholder copy

Color palette:

:root {
  --green: #3BBA7B;
  --green-light: #EAF7F0;
  --amber: #F59E0B;
  --red: #EF4444;
  --text: #1A1A2E;
  --text-muted: #6B7280;
  --bg: #F8FAFC;
  --card: #FFFFFF;
  --border: #E5E7EB;
}

---

Plain-text chat summary

After presenting the file, also output a short in-chat summary using emojis for scannability:

📅 [Client] — [Month Year]

📊 Key numbers
👥 Audience: [X] [↑/↓ X% vs last month]
👀 Impressions: [X]
💬 Engagement: [X] ([X]% rate)
📅 Posts: [X]

📱 By platform
[emoji] [Platform]: [X] impressions · [X]% eng rate · [X] posts
...

🏆 Top post: "[preview]" — [X] engagements

✅ What worked: [one line]
⚠️ Watch: [one line]

Keep the in-chat summary to ~15 lines max. The HTML file is the full deliverable.

---

Tone guidelines

• Write for a human reader, not a dashboard
• Use plain language — avoid jargon like "CTR optimization" or "algorithmic reach"
• Be specific with numbers; round where appropriate (e.g., "~12K" not "12,341")
• Don't pad with filler or repeat the same numbers in multiple sections
• If data is thin or the period was quiet, say so — don't oversell a slow month
• Emojis are used for navigation and scannability, not decoration — every emoji should label something

---

Edge cases

• Multi-workspace report: If the user wants a report across multiple clients, run Mode A per workspace and combine into a single summary with one section per client.
• Partial month: If the date range is mid-month, note this in the report header and caveat the numbers accordingly.
• No data / empty results: Say so clearly. Don't fabricate trends.
• CSV with multiple sheets: Ask the user which sheet to use, or process all sheets and note the sources.
• Competitor data in CSV: If the CSV contains competitor benchmarks, include a brief comparison section.