diagnose-performance

Use when the user asks why performance changed or what's going on with an account: ROAS dropped, CPA spiked, spend jumped, conversions fell, blended results slipped, or 'what moved this week'. Traces

SKILL.md

GitHub

Diagnose performance

Find the cause before changing the account. Trace a performance move to its real driver, then recommend the smallest action that fixes it.

When to use

  • "Why did ROAS drop last week?" / "Why is CPA up?"
  • "What changed in my account?" / "What moved this week?"
  • "Audit my Meta (or Google) account."
  • Blended results slipped and the user doesn't know which channel caused it.

Before you start

  1. Find the accounts (see get-started) and confirm the currency.
  2. Call recall_memory for the account: its baselines, targets, known patterns and earlier findings. Judge the move against this account's normal range, not a universal benchmark.
  3. Settle the comparison: the period in question vs the one before it (for example last 7 days vs the prior 7), and the target KPI (ROAS, CPA, CPL). If there's no target, use the account's trailing 30-day average and say so.

Workflow

1. The movement

Confirm the move is real before explaining it.

  • Pull both periods at account level for every channel involved.
  • Check that the change is outside normal variance and isn't partial data. Recent days can still be missing conversions.
  • Check volume. Ten conversions moving to eight is noise, not a trend.

2. The driver

Drill down one level at a time until the change is isolated to a specific line.

Where to look What it can show
Channel Which channel owns the move. Compare with GA4 sessions and conversions by channel, and Shopify revenue, to separate platform attribution from real business change.
Campaign → ad set / ad group → ad Where spend and results actually shifted. Quantify it: "Campaign X is 60% of spend and 90% of the CPA increase."
Changes in the account Budget, bid, targeting, status or creative edits right before the move.
Creative Hook rate, hold rate and CTR decay together with rising frequency means fatigue (see analyse-creative).
Audience and placement Delivery shifting to a worse segment, placement or geography.
Search terms New low-intent queries or match-type leakage (see clean-wasted-spend).
Auction CPM or CPC up with impression share down means competition, not quality.
Tracking Conversions falling while GA4 or Shopify stay flat usually means a tracking or attribution break, not a performance problem.

Apply the platform methodology:

  • Meta: meta-performance-analysis, with meta-depth-of-analysis. Read meta-custom-event-interpretation before judging any sales campaign that optimizes for COMPLETE_REGISTRATION.
  • Google: google-ads-search-analysis, google-ads-shopping or google-ads-pmax-evaluation, with google-ads-depth-of-analysis.
  • TikTok, LinkedIn, Microsoft Ads: the matching channel skill.
  • Before any recommendation, read meta-guardrails or google-ads-guardrails.

3. The proposed actions

Recommend the smallest change that addresses the driver. Refreshing creative is often better than cutting budget. For each action give the entity, what to change, the evidence, and the expected effect. Then surface one or two things the user didn't ask about but should know: a trend that will become a problem in the next 7–14 days.

Output

Use three parts:

  1. The movement. The metric, the change and the period, against the account's normal range. Example: "ROAS 2.1 vs a normal 2.8–3.2, down 27% week over week."
  2. The driver. The root cause with evidence. Example: "Hook rate and conversion rate fell together on the two top-spend ads, which are 70% of spend."
  3. The proposed actions. A ranked list with entity, change, reason and expected effect.

End by offering to make the changes (with approval) or to keep watching with an agent.

Acting on it

If the user wants to apply a fix, hand off to the matching skill: shift-budget, clean-wasted-spend or manage-campaigns. Every change goes dry run → the user approves in chat → live (see get-started).

Put it on a schedule

Offer a daily "performance analyst" agent that flags the next meaningful move (see automate-with-agents).

Tools

Source Tools
Meta Ads facebook_get_details_of_ad_account, facebook_get_adaccount_insights, facebook_get_async_adaccount_insights (large pulls), facebook_fetch_pagination_url, facebook_list_campaigns, facebook_list_adsets, facebook_list_ads, facebook_get_campaign_details, facebook_get_adset_details, facebook_get_activities_by_adaccount (change history)
Google Ads google_ads_run_gaql, google_ads_get_change_logs (changes joined with performance)
TikTok Ads tiktok_get_basic_report_enhanced, tiktok_get_async_report, tiktok_get_audience_report, tiktok_get_campaigns, tiktok_get_adgroups, tiktok_get_ads, tiktok_fetch_pagination, tiktok_get_change_log
LinkedIn Ads linkedin_get_ad_analytics, linkedin_get_campaigns
Microsoft Ads bing_ads_get_performance, bing_ads_get_change_history
GA4 google_analytics_run_report, google_analytics_get_traffic_sources (read ga4-source-of-truth first)
Shopify shopify_run_analytics_query (read shopify-order-discipline first)
Memory recall_memory

Reach, frequency and rate metrics can't be summed across rows. Recompute them from totals.