/ingest-performance

name: ingest-performance
description: "Feed last month's real numbers into next month's plan: ingest a platform analytics export (CSV from Instagram Insights, LinkedIn analytics, TikTok Studio, X analytics — any export with a post-id column) into per-post performance records, then rank the month's wins with sample floors and margin rules so ideation compounds measured winners, not remembered ones. Triggers on \"/ingest-performance\", \"here are last month's numbers\", \"import analytics\", \"which posts performed best\", \"engagement report\", \"what worked last month\", or whenever ideate-month needs its wins rung fed. Writes performance.json next to the month's tracker; /socialforge:ideate-month reads it and labels every win measured vs anecdotal."
argument-hint: "--brand <name> --month <YYYY-MM> [--csv <export.csv>] [--source <label>]"
user-invocable: true

/socialforge:ingest-performance — real numbers into the wins rung

`/socialforge:ideate-month` compounds "what worked last month." Before this skill, that meant whatever someone remembered in the planning call — and memory favors the post that felt good, not the one that performed. This skill turns the platform's own export into the record ideation reads.

Step 1 — Get the export

Ask the user for the analytics export covering the month. Any CSV works if it has a column identifying the post (`post_id`, `post`, `id`) that matches the calendar's post ids, plus whichever metrics the platform provides (impressions/views, likes/reactions, comments, shares/reposts, saves, clicks, follows — header aliases are normalized automatically). If the export keys posts by URL or caption instead of the calendar id, help the user add a `post_id` column first — matching is by calendar id, deliberately: wins must map back to the topics and pillars that produced them.

Step 2 — Ingest

python ${CLAUDE_PLUGIN_ROOT}/scripts/ingest_performance.py --action ingest \
    --brand {brand} --month {YYYY-MM} --csv {export.csv} --source "{platform} export"

• Rows matching calendar post ids are stored in

`output/{brand}/{month}/performance.json` (repeat ingests append — one CSV per platform is normal).

• **Unmatched rows are listed in the output, never silently dropped.** Show

the user the unmatched list; a typo'd id is data lost from the wins rung.

• Exit 3 = nothing matched. Stop and reconcile ids before proceeding.

Step 3 — Rank the wins

python ${CLAUDE_PLUGIN_ROOT}/scripts/ingest_performance.py --action wins \
    --brand {brand} --month {YYYY-MM}

The ranking is deliberately conservative:

• **Sample floor** (default 100 impressions): a post nobody saw cannot be a

win, only noise. Below-floor posts are reported as `unranked` with the reason.

• **Margin rule** (default 1.5× the month's median engagement rate): a "win"

must beat the month, not merely top a flat list.

• **Unmeasured is not zero**: missing impressions → `engagement_rate: null`,

and the post lands in `unranked`, not at the bottom of the ranking.

• A flat month returns `"status": "no_clear_wins"` — report that honestly.

Compounding a non-win manufactures a false signal for next month's plan.

Step 4 — Hand off to ideation

Relay the wins output to `/socialforge:ideate-month` (its "last month's results" input). Winners carry their topic, pillar, tier, and `vs_month_median` multiple, so ideation can design follow-ups that compound the validated angle — and label each one `measured` in "What last month validated". Anything the client reports that is NOT in the ranked output is still usable, labeled `anecdotal`.

Pairs with

• `/socialforge:ideate-month` — consumes the wins output; measured beats remembered
• `/socialforge:finalize-month` — closing a month is the natural moment to ingest its numbers