/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)

The analysis uses post-level metrics, so check their freshness: for each page, call `get_post_metrics_summary(workspaceId, [pageId], startDate, endDate)` and read `metricsFetchedAt.latest` (when the post metrics were last fetched). Keep its `totalPosts` for Step 2c.

• If it is **within the last 3 hours** — data is fresh. Skip the refresh entirely. Proceed to Step 2c.
• If it 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_post_metrics` for the stale pages and the date range (the analysis uses post-level metrics), plus `refresh_page_metrics` if you also need fresh page totals.

Both tools only queue a sync and return right away. Reading again immediately still returns the previous data; new data lands after a few minutes (Instagram is the slowest). Tell the user: > "Metrics are syncing — this can take a few minutes. I can run the analysis now with the most recent stored data, or check again in a few minutes."

Let the user decide. When checking again, call `get_post_metrics_summary` for the same pages and range and compare `metricsFetchedAt` with the time of the refresh: if it is newer, the sync completed. If it has not changed after a few minutes, the sync did not run: continue with the stored data and say how old it is in the Data notes. Proceed to Step 2c.

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 the chunks for that page in parallel, at most 3 at a time.** The analytics tools accept about 3 calls per second; extra calls are rejected with a "wait and retry" error, which is not a timeout, so retry those instead of skipping the range.

**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.

After the chunks for a page are done, compare the number of posts fetched with that page's `totalPosts`. If fewer came back, fetch the missing date ranges in smaller chunks, and record any gap that remains in Data notes.

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 rat