Update to Ad Superpowers

{
  "name": "meta-performance-troubleshooter",
  "description": "This skill should be used when the user asks to \"troubleshoot campaign performance\", \"diagnose delivery issues\", \"fix high CPA\", or mentions \"underperforming Meta ads\", \"Ad Relevance Diagnostics\", or \"kill vs scale decision\". Do NOT use for: learning phase issues (use learning-phase-tracker), bid strategy changes (use bid-strategy-selector), creative fatigue specifically (use creative-fatigue-analyzer).",
  "included_files": [],
  "skill_md_contents": "---\nname: meta-performance-troubleshooter\ndescription: \"This skill should be used when the user asks to \\\"troubleshoot campaign performance\\\", \\\"diagnose delivery issues\\\", \\\"fix high CPA\\\", or mentions \\\"underperforming Meta ads\\\", \\\"Ad Relevance Diagnostics\\\", or \\\"kill vs scale decision\\\". Do NOT use for: learning phase issues (use learning-phase-tracker), bid strategy changes (use bid-strategy-selector), creative fatigue specifically (use creative-fatigue-analyzer).\"\n---\n# Performance Troubleshooter\n\nDiagnostic framework for identifying and resolving Meta Ads performance problems.\n\n## Quick Diagnostic\n\n```\nWHAT IS THE PRIMARY SYMPTOM?\n│\n├─► No or low delivery\n│   └─► Go to [Delivery Issues]\n│\n├─► High CPA / Low ROAS\n│   └─► Go to [Efficiency Problems]\n│\n├─► Low CTR\n│   └─► Go to [Engagement Issues]\n│\n├─► High CPM\n│   └─► Go to [Auction Competition]\n│\n├─► Performance declining over time\n│   └─► Go to [Performance Decay]\n│\n└─► Conversions not tracked\n    └─► Go to [Tracking Issues]\n```\n\n## Diagnostic Framework\n\n### Step 1: Check Fundamentals\n\n```\nFUNDAMENTALS CHECKLIST:\n□ Pixel firing correctly? (⚠️ UI-only — no API for pixel diagnostics; check Events Manager)\n□ CAPI active? (Server events visible?)\n□ Event Match Quality? (⚠️ UI-only — EMQ score not available via API; check Events Manager)\n□ Attribution window correct? (Match buying cycle)\n□ Budget sufficient? (Min €50/day for learning)\n□ Audience size adequate? (Min 1M+ for prospecting)\n□ Creative variety? (Min 3-5 ads per ad set)\n```\n\n### Step 2: Ad Relevance Diagnostics\n\nMeta's 3 ranking metrics at ad level:\n\n| Metric | Meaning | Below Average = |\n|--------|---------|-----------------|\n| **Quality Ranking** | Perceived quality vs competitors | Improve creative/landing page |\n| **Engagement Rate Ranking** | Expected engagement vs competitors | Better hooks, more compelling creative |\n| **Conversion Rate Ranking** | Expected CVR vs competitors | Landing page issues, audience mismatch |\n\n### Step 3: Identify Root Cause\n\nUse diagnostic matrix below per symptom.\n\n## Delivery Issues\n\n### Symptom: No or Very Low Impressions\n\n```\nDIAGNOSE: Why no delivery?\n│\n├─► Ad Account Issues\n│   ├── Account restricted/disabled?\n│   ├── Payment method issue?\n│   └── Policy violation?\n│\n├─► Campaign Settings\n│   ├── Budget too low?\n│   ├── Bid/Cost cap too restrictive?\n│   ├── Schedule issues? (Ads not active?)\n│   └── Campaign paused?\n│\n├─► Audience Issues\n│   ├── Audience too small? (<50K)\n│   ├── Too many exclusions?\n│   ├── Geo targeting too narrow?\n│   └── Overlap with other campaigns?\n│\n├─► Ad Issues\n│   ├── Ads rejected/in review?\n│   ├── Low Quality Ranking?\n│   └── Policy flags?\n│\n└─► Competition Issues\n    ├── Auction outbid?\n    └── CPM spike in market?\n```\n\n### Solutions Matrix: Delivery\n\n| Issue | Diagnose Via | Solution |\n|-------|--------------|----------|\n| Budget too low | Spend vs budget | Increase to €50+/day |\n| Bid cap too low | Delivery insights | Increase 20-30% or switch to Lowest Cost |\n| Audience too small | Audience size estimate | Broader targeting, remove restrictions |\n| Ads rejected | Ad status | Fix policy issues, appeal if incorrect |\n| Low quality | Quality Ranking | Improve creative, landing page |\n| Outbid | Auction overlap | Increase bid or switch strategy |\n\n## Efficiency Problems\n\n### Symptom: High CPA / Low ROAS\n\n```\nDIAGNOSE: Why high CPA?\n│\n├─► Funnel Analysis\n│   ├── CPM normal, CTR low → Creative issue\n│   ├── CPM normal, CTR normal, CVR low → Landing page issue\n│   ├── CPM high, CTR normal → Audience/competition issue\n│   └── All metrics degraded → Multiple issues\n│\n├─► Funnel Metrics Checklist\n│   ├── CPM: €[X] (Benchmark: €15-25)\n│   ├── CTR: [X]% (Benchmark: 1-2%)\n│   ├── CPC: €[X] (Benchmark: €0.50-1.00)\n│   ├── LP → ATC: [X]% (Benchmark: 15%)\n│   ├── ATC → Purchase: [X]% (Benchmark: 30-50%)\n│   └── Overall CVR: [X]% (Benchmark: 2-5%)\n│\n└─► Identify Bottleneck\n    └─► Focus optimization effort there\n```\n\n### Solutions Matrix: Efficiency\n\n| Bottleneck | Symptom | Solution |\n|------------|---------|----------|\n| Creative | Low CTR | Test new hooks, formats, angles |\n| Targeting | High CPM, normal CTR | Broader audience, less competition |\n| Landing Page | High CTR, low CVR | UX audit, speed test, trust elements |\n| Offer | Good traffic, no sales | Price, value prop, urgency |\n| Tracking | Conversions missing | Fix Pixel/CAPI, check deduplication |\n| Attribution | Sales in GA but not Meta | Attribution window, cross-device |\n\n### Funnel Optimization Priority\n\n```\nPRIORITY ORDER:\n1. Fix tracking first (no data = optimizing blind)\n2. Landing page (often 2-3x lift possible)\n3. Creative (highest ongoing impact)\n4. Targeting (let AI help)\n5. Bid strategy (fine-tuning)\n\nROI PER FIX:\n├── Tracking: 50-200% improvement possible\n├── Landing page: 20-100% CVR lift\n├── Creative: 20-50% CTR lift\n├── Targeting: 10-30% efficiency gain\n└── Bid strategy: 5-15% fine-tuning\n```\n\n## Engagement Issues\n\n### Symptom: Low CTR\n\n```\nCTR BENCHMARK:\n├── Poor: <0.8%\n├── Average: 0.8-1.5%\n├── Good: 1.5-2.5%\n└── Excellent: >2.5%\n\nLOW CTR CAUSES:\n│\n├─► Creative Issues\n│   ├── Weak hook (first 3 sec video)\n│   ├── Unclear value proposition\n│   ├── Poor visual quality\n│   ├── Wrong format for placement\n│   └── Creative fatigue\n│\n├─► Targeting Issues\n│   ├── Irrelevant audience\n│   ├── Audience too broad\n│   └── Message-audience mismatch\n│\n└─► Ad Copy Issues\n    ├── Weak headline\n    ├── No clear CTA\n    └── Benefits unclear\n```\n\n### Solutions: Low CTR\n\n```\nCREATIVE FIXES:\n├── Test 5+ new hook variations\n├── A/B test headlines\n├── Try different formats (video vs static)\n├── Update visuals/thumbnails\n└── Add motion/animation\n\nTARGETING FIXES:\n├── Narrow to higher-intent segments\n├── Test different interest combinations\n├── Create lookalikes from purchasers\n└── Exclude low-engagement segments\n\nCOPY FIXES:\n├── Lead with benefit, not feature\n├── Add social proof\n├── Create urgency\n└── Clearer, action-oriented CTA\n```\n\n## Auction Competition\n\n### Symptom: High CPM\n\n```\nCPM BENCHMARK:\n├── Low: <€10\n├── Average: €15-25\n├── High: €25-40\n└── Very High: >€40\n\nHIGH CPM CAUSES:\n│\n├─► Market Factors\n│   ├── Peak season (Q4, Black Friday)\n│   ├── Industry competition spike\n│   └── Major events/elections\n│\n├─► Targeting Factors\n│   ├── Very competitive audience\n│   ├── Small audience (premium pricing)\n│   └── Overlapping with own campaigns\n│\n└─► Quality Factors\n    ├── Low relevance score\n    ├── Poor engagement history\n    └── New ad account (no history)\n```\n\n### Solutions: High CPM\n\n```\nIMMEDIATE ACTIONS:\n├── Expand audience (larger = cheaper)\n├── Remove restrictive targeting\n├── Test different placements (including Threads — new March 2026, lower CPM early stage)\n├── Check audience overlap tool\n\nSTRATEGIC ACTIONS:\n├── Improve ad quality (better auction position)\n├── Test off-peak timing\n├── Build lookalikes from best customers\n└── Diversify to less competitive channels\n\nSEASONAL STRATEGY:\n├── Pre-peak: Lock in audiences, test creatives\n├── Peak: Accept higher CPM, focus on ROAS\n└── Post-peak: Capitalize on lower competition\n```\n\n## Performance Decay\n\n### Symptom: Metrics Declining Over Time\n\n```\nDECAY DIAGNOSIS:\n│\n├─► Creative Fatigue\n│   ├── Symptoms: Rising frequency, falling CTR\n│   ├── Threshold: Frequency >3-4\n│   └── Solution: Fresh creative rotation\n│\n├─► Audience Saturation\n│   ├── Symptoms: Shrinking reach, high frequency\n│   ├── Threshold: Reached >70% of audience\n│   └── Solution: Expand targeting, new audiences\n│\n├─► Seasonal Effects\n│   ├── Symptoms: Industry-wide decline\n│   └── Solution: Adjust expectations, test new offers\n│\n├─► Competitor Activity\n│   ├── Symptoms: CPM up, CTR down\n│   └── Solution: Differentiate, refresh positioning\n│\n└─► Algorithm Changes\n    ├── Symptoms: Sudden performance shift\n    └── Solution: Adapt to new best practices\n```\n\n### Creative Fatigue Detection\n\n```\nFATIGUE INDICATORS:\n□ CTR dropping week-over-week\n□ Frequency >4 in past 7 days\n□ Same creative running >14-21 days\n□ Engagement Rate Ranking declining\n□ CPM increasing without market shift\n\nREFRESH CADENCE:\n├── High-spend campaigns: Every 7-14 days\n├── Medium-spend: Every 14-21 days\n├── Low-spend: Every 21-30 days\n└── Evergreen/testimonials: Can run longer\n```\n\n## Tracking Issues\n\n### Symptom: Conversions Not Tracked\n\n```\nTRACKING DIAGNOSTIC:\n│\n├─► Pixel Issues\n│   ├── Pixel not installed correctly\n│   ├── Pixel blocked by ad blockers\n│   ├── Event not firing on conversion\n│   └── Wrong pixel ID\n│\n├─► CAPI Issues\n│   ├── CAPI not configured\n│   ├── Events not deduplicating\n│   ├── Low Event Match Quality\n│   └── Token expired\n│\n├─► Attribution Issues\n│   ├── Wrong attribution window\n│   ├── Cross-device not tracked\n│   ├── Long purchase cycle\n│   └── iOS privacy impact\n│\n└─► Technical Issues\n    ├── Thank you page not loading\n    ├── Redirect issues\n    └── Tag manager conflicts\n```\n\n### Tracking Fix Checklist\n\n```\nQUICK FIXES:\n□ Test Pixel with Meta Pixel Helper (⚠️ UI-only — browser extension)\n□ Check Events Manager for recent events (⚠️ UI-only — event diagnostics not in API)\n□ Verify domain is verified\n□ Confirm event parameters (value, currency)\n□ Check for duplicate events\n\nCAPI VERIFICATION (⚠️ all UI-only — Events Manager required):\n□ Server events visible in Events Manager?\n□ Deduplication working? (Same event from 2 sources)\n□ Event Match Quality >7?\n□ Customer parameters hashed correctly?\n\nATTRIBUTION CHECK:\n□ Attribution window matches buying cycle\n□ GA4 comparison (same trends?)\n□ Post-purchase survey attribution\n```\n\n## Kill vs Scale Decision\n\n### Decision Framework\n\n```\nSCALE SIGNALS (Increase Budget):\n├── ROAS >target for 5+ days\n├── CPA <target and stable\n├── CTR above benchmark\n├── Frequency <3\n├── Room to grow in audience\n└── Consistent daily performance\n\nOPTIMIZE SIGNALS (Test & Tweak):\n├── ROAS within 20% of target\n├── CPA fluctuating but manageable\n├── Some ads performing, others not\n├── Creative starting to fatigue\n└── Potential with adjustments\n\nKILL SIGNALS (Pause/Stop):\n├── ROAS <1x (losing money)\n├── CPA >2x target for 7+ days\n├── CTR <0.5% consistent\n├── No improvements despite tests\n├── Insufficient budget for learning\n└── Audience exhausted\n```\n\n### Kill Decision Checklist\n\n```\nBEFORE KILLING, VERIFY:\n□ Tracking is accurate (not a tracking issue)\n□ Attribution window appropriate\n□ Gave sufficient time (7+ days minimum)\n□ Tested multiple creatives\n□ Budget was adequate\n□ Not during anomaly period (holiday, etc.)\n\nIF ALL VERIFIED, THEN:\n├── Killing = correct decision\n├── Document learnings\n├── Archive for reference\n└── Reallocate budget to winners\n```\n\n## MCP: Pull Performance Data for Diagnosis\n\n```python\n# Get campaign-level performance metrics\nmeta_get_insights(account_id=\"act_XXXXX\", level=\"campaign\", date_preset=\"last_7d\", fields=[\"spend\",\"impressions\",\"clicks\",\"ctr\",\"cpm\",\"cpc\",\"actions\",\"cost_per_action_type\",\"frequency\"])\n\n# Get ad-level breakdown to isolate creative issues\nmeta_get_insights(account_id=\"act_XXXXX\", level=\"ad\", date_preset=\"last_7d\", fields=[\"spend\",\"impressions\",\"clicks\",\"ctr\",\"frequency\",\"actions\",\"quality_ranking\",\"engagement_rate_ranking\",\"conversion_rate_ranking\"])\n```\n\n## Troubleshooting Output Template\n\n```markdown\n# Campaign Troubleshooting Report\n\n## Campaign Overview\n- Campaign: [name]\n- Objective: [objective]\n- Daily Budget: €[X]\n- Running since: [date]\n- Current Status: [status]\n\n## Symptom Analysis\n**Primary symptom:** [description]\n**Duration:** [since when]\n**Severity:** [Low/Medium/High/Critical]\n\n## Diagnostic Results\n\n### Fundamentals Check\n- [x] Pixel: [OK/Issue]\n- [x] CAPI: [OK/Issue]\n- [x] EMQ: [score]\n- [x] Budget: [OK/Issue]\n- [x] Audience: [OK/Issue]\n\n### Key Metrics\n| Metric | Current | Benchmark | Status |\n|--------|---------|-----------|--------|\n| CPM | €[X] | €15-25 | [OK/High/Low] |\n| CTR | [X]% | 1-2% | [OK/High/Low] |\n| CPC | €[X] | €0.50-1 | [OK/High/Low] |\n| CVR | [X]% | 2-5% | [OK/High/Low] |\n| CPA | €[X] | €[target] | [OK/High] |\n| ROAS | [X]x | [target]x | [OK/Low] |\n\n### Root Cause Identified\n[Description of root cause]\n\n## Recommended Actions\n\n### Immediate (This Week)\n1. [Action 1]\n2. [Action 2]\n\n### Short-term (2-4 Weeks)\n1. [Action 1]\n2. [Action 2]\n\n### Monitor\n- [Metric 1]: Watch for [threshold]\n- [Metric 2]: Watch for [threshold]\n\n## Prognosis\n[Expected outcome if recommendations followed]\n```\n"
}