/content-pattern-intelligence

name: content-pattern-intelligence
description: >
  Analyze top-performing posts across three performance lenses — engagement, impressions,
  and engagement rate — to identify content patterns and give the user specific hypotheses
  to test in their next posts. Use this skill whenever the user asks things like "what's
  working in my content", "what should I post more of", "why are some posts doing better",
  "what patterns do you see", "give me content ideas based on my best posts", "what content
  works best for [client]", "analyze my top posts", or "what should I try next month".
  Also activate when the user wants to understand performance beyond just numbers — when
  they're asking for creative direction, not just a report. Always use this skill instead
  of a generic performance summary when the user's goal is to improve future content.

Content pattern intelligence

Look at what's actually working — then tell the user why, and what to try next.

This skill analyzes top posts across three performance lenses, finds patterns in the content itself (format, hook, topic, tone, structure), and translates them into specific, testable hypotheses for future posts.

**This is not a performance report.** It's a content brief grounded in data.

---

Step 0: Detect input mode

**Mode A — Planable connector** User has Planable connected and wants to pull live post data.

**Mode B — CSV upload** User has uploaded a CSV export with post-level data (text, date, platform, metrics).

**How to detect:**

• File uploaded → Mode B
• Mentions "CSV", "export", "file", "spreadsheet" → Mode B
• Mentions workspace name, client, or Planable → Mode A
• Unclear → ask: "Do you have a CSV with your post data, or should I pull it from Planable?"

---

Mode A: Planable connector

Step 1: Gather inputs

• **Workspace / client** — which workspace to analyze
• **Platform(s)** — default to all; narrow if requested
• **Date range** — default to last 60–90 days (needs enough posts to find patterns; warn if fewer than 15 posts available)

Step 2: Fetch data — with Instagram-safe refresh logic

Instagram metrics sync is async and slow. Always follow this sequence to avoid timeouts.

**Always call `get_post_metrics` with exactly one `pageId` per request. Multi-page calls compound timeouts — never bundle multiple pages into a single call.**

Step 2a: Read first, check freshness

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

For each page in the response, check `lastMetricAt` (the timestamp of the last successful metrics fetch).

• If `lastMetricAt` is **within the last 3 hours** — data is fresh. Skip the refresh entirely. Proceed to Step 2c.
• If `lastMetricAt` is **older than 3 hours** or missing — data is stale. Proceed to Step 2b.

The `posts` field in the `get_page_metrics` response tells you the post count per page for the window. Record it now — use it to plan chunk size in Step 2c so you're not choosing a strategy inside the fetch loop.

Step 2b: Refresh stale data — with platform-aware patience

Call `refresh_page_metrics` for the stale pages.

For **Instagram pages specifically**, tell the user before refreshing: > "Instagram metrics are syncing — this can take 1-2 minutes. I'll check back once the data is ready."

Then wait before re-reading:

• **Instagram:** wait 60 seconds before calling `get_page_metrics` again
• **All other platforms:** wait 15-20 seconds

After waiting, call `get_page_metrics` again and re-check `lastMetricAt`:

• If `lastMetricAt` is now more recent than the refresh call — sync completed. Proceed to Step 2c.
• If `lastMetricAt` is still older — sync is still in progress. Wait another 30 seconds and retry once more.
• After 2 retries with no update — tell the user: "Instagram data is still syncing. You can try again in a few minutes, or I can run the analysis now using the most recent available data." Let the user decide.

Step 2c: Fetch post-level metrics (volume-aware)

Process each page individually — never bundle multiple pages in one call.

For each page, follow this sequence:

**1. Check post volume** Use the `posts` field already captured in Step 2a for this page. If it wasn't available there, call:

get_post_metrics_summary(workspaceId, [pageId], startDate, endDate)

→ read `totalPosts` for the window.

**2. Choose chunk size based on `totalPosts`**

| Posts in window | Strategy | |---|---| | ≤ 20 | Fetch full window in one call | | 21–40 | Two 45-day chunks | | 41–80 | ~6 chunks of 2 weeks each | | 80+ | 1-week chunks |

**3. Run all chunks for that page in parallel.**

**4. On timeout for any chunk — bisect:**

• Halve the failing window and retry both halves.
• If a window shrinks below 48 hours and still times out, **stop bisecting**.
• Skip that range entirely.
• Record it in Data notes: e.g. "1 IG post in May 12–14 likely missing — endpoint timed out at < 48h window."
• Do not retry further — the rest of the dataset is still usable.

Repeat for each page before moving on to Step 3.

Step 3: Sort into three ranked lists -> go to [Analysis](#analysis)

---

Mode B: CSV upload

Step 1: Accept the file

If no file uploaded yet: "Please upload a CSV with your post data — it should include post text, platform, and at least one of: likes, comments, shares, impressions, or engagement rate."

Supported sources: Planable Analytics export, Meta Business Suite, LinkedIn Analytics, Hootsuite, Sprout Social, or any post-level CSV.

Step 2: Parse the CSV

Identify:

• **Post text column** — `text`, `caption`, `message`, `content`, or similar
• **Platform column** — `platform`, `channel`, `network`, `page`
• **Engagement columns** — likes, comments, shares, reactions, saves, clicks → sum into total engagement if not pre-summed
• **Impressions column** — `impressions`, `reach`, `views`
• **Engagement rate column** — `engagement_rate`, `eng_ra