Update to Motion

{
  "description": "Analyze creative performance — what's working, what's scaling, what's dying. Multi-metric analysis with demographic breakdown and actionable recommendations.",
  "included_files": [
    {
      "relative_path": "references/campaign-context.md",
      "size_in_bytes": 8493
    }
  ],
  "name": "performance-analysis",
  "skill_md_contents": "---\nname: performance-analysis\ndescription: Analyze creative performance — what's working, what's scaling, what's dying. Multi-metric analysis with demographic breakdown and actionable recommendations.\nargument-hint: \"[--datePreset LAST_30_DAYS] [--limit 10] [--metric goalMetric]\"\nallowed-tools:\n  - Read\n  - Agent\n  - \"mcp__ruimotion__get_auth_context\"\n  - \"mcp__ruimotion__get_creative_insights\"\n  - \"mcp__ruimotion__get_demographic_breakdown\"\n  - \"mcp__ruimotion__get_glossary_values\"\n  - \"mcp__ruimotion__get_workspace_brand\"\n  - AskUserQuestion\nmodel: opus\n---\n\n# Creative Performance Analysis\n\nAnalyze creative performance using the creative-strategist skill methodology — multi-metric landscape, demographic overlay, and creative taxonomy. Produce an actionable report of what's working, what's scaling, and what's dying.\n\n---\n\n## Phase 0: Orient\n\nBefore pulling data:\n\n1. **Acknowledge**: \"I'll analyze your creative performance to find what's working, scaling, and dying.\"\n2. **Detect complexity**: Is this a quick question (\"how's ROAS?\") or a full deep dive (\"what's working?\")? Quick questions get 1-2 tool calls and a direct answer. Full analysis gets the multi-metric sweep.\n3. **Ask if ambiguous**: \"Quick top-line or full deep dive? Any specific metric or time period you care about?\"\n4. **Connected workflow**: After analysis, you can create concepts (`/create-concepts`), find iterations (`/find-iterations`), or dive into a specific ad (`/analyze-ad`).\n\nIf the user provides clear, specific intent (e.g., \"full performance analysis for last 30 days\"), skip questions and deliver.\n\n---\n\n## Phase 1: Setup\n\n### 1a. Parse Arguments\n\n- `--datePreset`: Time window for analysis. Default: `LAST_30_DAYS`. Options: TODAY, YESTERDAY, THIS_MONTH, LAST_MONTH, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_90_DAYS.\n- `--limit`: Max creatives per metric query. Default: `10`.\n- `--metric`: Optional focus metric (SPEND, SCALING, HOOK, CPC, CTR_ALL, PURCHASES, PURCHASE_VALUE, or the workspace's goalMetric). If provided, lead the analysis with this metric. If not, use the standard multi-metric approach.\n\n### 1b. Load Settings & Auth\n\n1. Read `${CLAUDE_PLUGIN_ROOT}/motion-creative.config.md` for org-specific configuration. If the file does not exist, use these defaults and suggest the user run `/customize`:\n   - `primary_kpi`: use goalMetric from first `get_creative_insights` response\n   - `default_date_preset`: LAST_30_DAYS\n   - `default_creative_limit`: 10\n   - `demographic_focus`: both\n   - `primary_metrics` / `secondary_metrics` / `exclude_metrics`: auto-detect\n   - `priority_glossary_categories`: use all\n   - Brand guidelines: pull from `get_workspace_brand`\n2. Call `get_auth_context()` to resolve workspaceId (use settings workspace_id as fallback context).\n3. If settings contain a `primary_kpi` and no `--metric` was specified, use the primary KPI to lead the analysis.\n4. If settings contain `target_demographics`, weight demographic analysis toward those segments.\n5. If settings contain `primary_metrics`, ensure those metrics lead the analysis. If `secondary_metrics`, include after primary. If `exclude_metrics`, omit those from all queries and output.\n6. Use `default_date_preset` from settings as the datePreset for all calls unless the user provided a `--datePreset` argument. Use `default_creative_limit` from settings as the limit unless the user provided a `--limit` argument.\n\nIf auth fails, stop and tell the user to check their Motion workspace connection.\n\n### 1c. Load Methodology\n\nRead the creative-strategist skill and `references/performance-metrics.md` for metric definitions and interpretation patterns.\n\n---\n\n## Phase 2: Data Collection\n\n**The SPEND call must come first** (it returns goalMetric and spendThreshold). Then dispatch remaining calls in parallel.\n\n1. `get_creative_insights(workspaceId, insightType=\"SPEND\", datePreset, limit, withAggregatedInsights=true)` — spend leaders + account-level aggregates\n\n→ Extract `goalMetric` and `spendThreshold` from the response. Use goalMetric for all efficiency-sorted calls.\n\n2. `get_creative_insights(workspaceId, insightType=\"SCALING\", datePreset, limit)` — what's gaining/losing allocation\n3. `get_creative_insights(workspaceId, insightType=goalMetric, datePreset, limit)` — efficiency leaders by workspace goal metric\n4. `get_creative_insights(workspaceId, insightType=\"HOOK\", datePreset, limit)` — thumbstop rate leaders\n5. `get_demographic_breakdown(workspaceId, datePreset)` — age/gender performance\n6. `get_glossary_values(workspaceId)` — creative taxonomy categories\n\nIf `--metric` is specified, ensure that metric is included and prioritized in the analysis.\n\n---\n\n## Phase 3: Analysis\n\n### 3a. Build Creative-Level View\n\nFor each creative appearing across the results, collect:\n- Its rank/position in each metric query it appeared in\n- Key performance values (spend, goalMetric, hook rate, and other relevant metrics)\n- Whether it's scaling, stable, or declining\n- **Its campaign and ad set context** — `campaignName`, `campaignIds`, `adsetName`, `adsetIds`\n\nCross-reference to identify:\n- **All-rounders:** Creatives that appear in top results across multiple metrics\n- **Specialists:** High on one metric but absent from others (e.g., high HOOK but not in goalMetric top — hooks but doesn't convert)\n- **Hidden gems:** Strong goalMetric but low spend — underexploited\n\n### 3a-ii. Map Campaign & Ad Set Structure\n\nThis step is critical — **campaign and ad set context changes the meaning of every metric.**\n\n1. **Group creatives by campaign**, then by ad set within each campaign\n2. Apply campaign tier classification and structural issue detection from `references/campaign-context.md`\n\nConsult `references/campaign-context.md` for campaign tier naming heuristics, ad set strategy signals, and structural issue patterns.\n\n### 3b. Pattern Extraction\n\nUse glossary values to tag each creative with its taxonomy categories. Then analyze:\n- Which categories (format, hook type, asset type, messaging angle) are over/under-represented in top performers?\n- Which categories are scaling vs. declining?\n- What combinations appear in winners but not losers?\n- What hasn't been tried? (categories with zero or minimal coverage)\n- **Which campaign tiers favor which creative patterns?** (e.g., UGC dominates testing but studio images dominate scaling — or vice versa)\n\nConsult `references/performance-metrics.md` for metric combination stories.\n\n### 3c. Demographic Analysis\n\nFrom the demographic breakdown:\n- Which age/gender segments drive the best performance?\n- Are there underserved segments where creative investment could expand?\n- Do certain creatives skew strongly toward one demographic?\n\n### 3d. Apply Brand Context from Settings\n\nIf config contains brand guidelines (Brand Voice, Creative Do's/Don'ts, Target Audience):\n- Frame recommendations through brand constraints — don't suggest approaches that violate creative don'ts\n- Weight audience insights toward the brand's stated target audience\n- Use brand voice to inform how insights are framed\n\nIf settings contain `priority_glossary_categories`, prioritize those categories in pattern extraction (3b).\n\n### 3e. Apply Insight Quality Bar\n\nBefore writing findings, check each insight against `references/insight-quality.md`. Every finding must explain the \"why\" — what's happening in the viewer's mind — not just state a metric.\n\n---\n\n## Phase 4: Output\n\nOpen by reflecting what data you pulled: time window, number of creatives analyzed, any filters applied. Keep it conversational — one sentence, not a formatted log.\n\n### Report Structure\n\n**If You Read Nothing Else**\n3-5 bullets. The most actionable findings. Lead with what changed or what's surprising. Every bullet should make the reader want to do something.\n\n**Top Performers**\nCreatives with the best combination of goal metric efficiency + meaningful spend. Not just highest efficiency (which could be low-spend noise). Show the creative, its key metrics, **which campaign/ad set it runs in**, and WHY it works — the behavioral insight. Contextualize efficiency against the campaign tier (e.g., below-breakeven on cold prospecting may be acceptable if LTV justifies it; below-breakeven on scaling is a problem).\n\n**Scaling Winners**\nCreatives gaining spend allocation with stable or improving efficiency. These are the ones the algorithm is betting on. Note what they have in common. **Flag whether they're scaling in an uncapped environment (strong signal) or a cost-cap environment (inflated signal).**\n\n**Efficiency Standouts**\nStrong goalMetric but not yet scaling — hidden gems that deserve more budget. Explain why they might be underexploited. **Note their campaign context — a gem in a cost-cap ad set needs uncapped validation before you declare it a winner.** Recommend the graduation path: which campaign/ad set to move it to next.\n\n**Campaign Structure Issues**\nStructural problems in how campaigns and ad sets are organized that work against performance. This section surfaces:\n- Testing creatives competing with proven winners inside the same CBO (budget starvation)\n- \"Top performers\" ad sets containing fatigued creatives (budget traps)\n- Creatives ready to graduate from Testing → Scaling\n- CBO allocation conflicts where budget flows to high-spend losers over low-spend winners\n- Cost-cap artifacts inflating efficiency metrics\n\n**Declining Creatives**\nLosing share or performance dropping. Don't just flag them — recommend what to do: refresh, pause, test new hooks on the same body, etc. **If a declining creative sits in a \"Top performers\" ad set, explicitly recommend removal — it's dragging down the ad set.**\n\n**Demographic Sweet Spots**\nWhere performance concentrates by age/gender. Which segments are strongest, which are underserved, and what that means for creative strategy.\n\n**Recommendations**\n3-5 specific next actions. Each recommendation must be:\n- Specific enough to act on today\n- Grounded in a finding from the analysis\n- Framed as \"do this because the data shows X\"\n- **Campaign-aware** — recommendations should specify where creatives should move (e.g., \"graduate BRoll TO from Testing 1 to Top performers ad set\"), not just \"increase budget\"\n\n---\n\n## Error Handling\n\n- **Auth fails:** Stop and tell user to check Motion workspace connection\n- **One metric query fails:** Note the gap, continue with remaining data\n- **All queries fail:** Report the failure, suggest checking the Motion MCP connection\n- **Empty results:** Note that no creatives match the criteria — suggest broadening the datePreset or checking spend thresholds\n- **Limited data (few creatives):** Adjust analysis depth — don't over-interpret small samples\n"
}