Update to Billy Grace Insights

{
  "name": "billy-grace-analysis",
  "description": "Interpret Billy Grace marketing results: analyze campaign performance, explain ROAS and CPA, apply funnel stages, optimize budgets, compare channels, evaluate creative performance, and diagnose why performance changed. Use whenever the user asks what the numbers mean, why results moved, or how to improve them, even if they never say \"analysis\". Do not use to build or run the query that fetches the data (use billy-grace-data-retrieval), or to pick attribution models, modes, or windows (use billy-grace-attribution).\n",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 409
    },
    {
      "relative_path": "references/budget-optimization.md",
      "size_in_bytes": 4185
    }
  ],
  "skill_md_contents": "---\nname: billy-grace-analysis\ndescription: >\n  Interpret Billy Grace marketing results: analyze campaign performance,\n  explain ROAS and CPA, apply funnel stages, optimize budgets, compare\n  channels, evaluate creative performance, and diagnose why performance\n  changed. Use whenever the user asks what the numbers mean, why results\n  moved, or how to improve them, even if they never say \"analysis\". Do not\n  use to build or run the query that fetches the data (use\n  billy-grace-data-retrieval), or to pick attribution models, modes, or\n  windows (use billy-grace-attribution).\nmetadata:\n  author: Billy Grace\n  version: 1.1.0\n  mcp-server: billy-grace-insights-mcp\n---\n\n# Billy Grace Marketing Analysis\n\nThis skill teaches you how to interpret marketing performance data retrieved from the Billy Grace MCP server and provide actionable, strategically sound advice. The guidance here reflects Billy Grace's domain expertise as a marketing optimization platform.\n\nWhen users compare Billy Grace numbers to ad-platform or web-analytics reporting, differences are expected: Billy Grace attributes over identity-resolved customer journeys rather than fragmented sessions (see the **billy-grace-attribution** skill).\n\n## Performance metrics\n\n### Core metrics\n\n| Metric | What it measures | When it matters |\n|--------|-----------------|-----------------|\n| `spend` | Budget invested in a campaign | Understanding pacing and budget distribution |\n| `event_value` | Attributed revenue (or value) from the custom event | Measuring return on marketing investment |\n| `number_of_events` | Attributed count of conversions | Volume of desired outcomes |\n| `impressions` | Number of times ads were shown | Reach and awareness |\n| `clicks` | Number of ad clicks | Engagement and traffic generation |\n| `sessions` | Website sessions from marketing | Traffic volume |\n\n### Computed metrics\n\nThese metrics may be returned by the server or may need to be computed from raw data. Always verify you have the component values and compute them yourself when the server does not return them.\n\n| Metric | Formula | Interpretation |\n|--------|---------|----------------|\n| `roas` | event_value / spend | Revenue generated per euro spent. Higher is better. Only meaningful for revenue-type events and **paid channels with spend > 0**. |\n| `cpa` | spend / number_of_events | Cost to acquire one conversion. Lower is better. Works for both revenue and non-revenue events. Guard against division by zero when a channel has no conversions. |\n| `conversion_rate` | (number_of_events / sessions) * 100 | Percentage of sessions that convert. Indicates landing page and funnel effectiveness. |\n| `cost_per_click` | spend / clicks | Price per click. Rising CPC with stable CTR may signal increased auction competition. |\n\nWhen computing these from raw data, handle edge cases: skip ROAS/CPA for rows where `spend` is 0 (non-paid channels), and skip CPA where `number_of_events` is 0.\n\n### Additional metrics (not available for all clients)\n\n| Metric | What it measures |\n|--------|-----------------|\n| `new_customer` | Conversions from first-time buyers |\n| `returning_customer` | Conversions from existing customers |\n| `new_customer_revenue` | Revenue from new customers |\n| `returning_customer_revenue` | Revenue from returning customers |\n| `pre_spend_profit` | Gross profit before subtracting ad spend |\n\n### New vs returning customer metrics\n\nWhen available, `new_customer`, `returning_customer`, `new_customer_revenue`, and `returning_customer_revenue` reveal the health of acquisition vs retention:\n\n- **High returning_customer share with low new_customer**: the brand is retaining well but may not be growing its customer base. TOFU investment could be underfunded.\n- **High new_customer share with low returning_customer**: acquisition is working but retention is weak. Check email/CRM flows and post-purchase experience.\n- **new_customer_revenue vs returning_customer_revenue**: returning customers often have higher AOV. A drop in returning_customer_revenue may signal churn, not a marketing problem.\n\n## Custom event types\n\nCustom events are user-defined conversions (e.g., \"purchase\", \"form_send\", \"demo_booked\"). They fall into two categories, and the distinction determines which metrics make sense:\n\n### Revenue events (e.g., purchase, order_completed, subscription_started)\n\nThe `event_value` translates directly to monetary value. Use **ROAS** (event_value / spend) as the primary efficiency metric.\n\n### Non-revenue events (e.g., form_send, demo_booked, call_scheduled)\n\nThe `event_value` does not represent money, so ROAS is meaningless. Use **CPA** (spend / number_of_events) instead. The goal is minimizing cost per conversion, not maximizing a revenue ratio.\n\nAlways confirm which type of event the user is analyzing before choosing metrics.\n\n## Funnel stages\n\nMarketing campaigns serve different roles depending on where in the funnel they operate. Interpret performance relative to the campaign's funnel stage, not in absolute terms.\n\n### TOFU (Top of Funnel) -- Awareness\n\n**Purpose**: reach cold audiences unfamiliar with the brand.\n\n- Expect high impressions, low direct conversions, and higher CPA. This is normal -- TOFU is investing in future demand.\n- Platforms typically used: Meta, TikTok, Snapchat, YouTube, TV, Radio.\n- Only classify as BOFU when \"retargeting\" appears in the campaign name.\n\n### MOFU (Middle of Funnel) -- Consideration\n\n**Purpose**: nurture users who previously engaged with TOFU content.\n\n- Targets warm audiences: site visitors, video viewers, email subscribers.\n- Performance should be between TOFU and BOFU.\n\n### BOFU (Bottom of Funnel) -- Conversion\n\n**Purpose**: convert high-intent users close to purchasing.\n\n- Expect strong ROAS, low CPA, and high conversion rates. This is where direct ROI shows up.\n- Platforms typically used: Google/Bing Search, retargeting campaigns on any platform.\n- Only classify Google/Bing Search as TOFU/MOFU when \"display\" appears in the name.\n\n### Interpreting performance across the funnel\n\nComparing a TOFU campaign's ROAS to a BOFU campaign's ROAS is like comparing a seed to a harvest. TOFU feeds the funnel that BOFU harvests. Evaluate each stage against its own purpose:\n\n- TOFU: reach, impressions, video views, new audience growth\n- MOFU: engagement, CTR, site traffic quality\n- BOFU: ROAS, CPA, conversion rate, revenue\n\n## Diagnostic playbook: investigating performance changes\n\nWhen a user reports that a metric changed (e.g. \"ROAS dropped,\" \"CPA spiked,\" \"conversions fell\"), follow this investigation workflow:\n\n### Step 1: Establish baseline with supporting metrics\n\nFetch the primary metric AND its supporting metrics (see below) for the current period and a comparison period (previous week, previous month, or same period last year). Include supporting metrics in the initial query to avoid extra round-trips -- a ROAS investigation should request `roas`, `event_value`, `number_of_events`, `spend`, `cpa`, `clicks`, and `cost_per_click` upfront.\n\nUse the **billy-grace-data-retrieval** skill to make two `insights_query` calls with different date ranges.\n\n### Step 2: Isolate the scope\n\nIf the user already names a specific channel (e.g., \"Google Ads\"), start the investigation filtered to that channel using `dimension_filter_mapping` and break down by `campaign_name`. If no specific channel is mentioned, first break down by `source` to see if the change affects everything or specific channels, then drill into `campaign_name` for the affected channel.\n\n### Step 3: Interpret supporting metrics\n\nA single metric rarely tells the full story. When investigating:\n\n- **ROAS dropped**: check `cpa`, `event_value`, `number_of_events`, and `spend`. Did revenue fall? Did spend increase? Did conversions decrease?\n- **CPA increased**: check `spend`, `number_of_events`, `clicks`, `cost_per_click`. Is spend up, or are conversions down?\n- **CTR falling**: check `impressions` and `clicks` separately. Is the audience seeing more impressions (frequency issue / creative fatigue) or are fewer people clicking (relevance issue)?\n\n### Step 4: Rule out data and attribution artifacts\n\n- **Conversion lag**: if using a long attribution window and looking at recent data, the dip may be an artifact of incomplete attribution. Consult the **billy-grace-attribution** skill.\n- **Incomplete data**: check for zero event_value across all campaigns, which signals a data pipeline issue, not a real performance drop.\n- **Campaign status**: include `campaign_status` in the breakdown to check whether campaigns were paused during the period.\n\n### Step 5: Form and communicate hypotheses\n\nBased on the evidence, propose likely explanations framed as hypotheses (see Communication style below). Suggest next steps the user can take to confirm or act on the findings.\n\n## Campaign name interpretation\n\nCampaign names often encode funnel stage, objective, targeting, and market. Common patterns in the data:\n\n- **\"Conversie\" / \"Conversion\"** → BOFU objective. Expect strong ROAS/CPA.\n- **\"Prospecting\" / \"Awareness\" / \"Reach\"** → TOFU objective. Expect high impressions, weaker direct ROAS.\n- **\"Retargeting\" / \"Remarketing\"** → BOFU, harvesting warm audiences.\n- **\"Brand\" / \"Branded\"** → Capturing existing demand. High ROAS is expected but not scalable.\n- **\"PMax\" / \"pMax\" / \"Catch-All\"** → Google Performance Max. Mixed funnel; evaluate holistically.\n- **\"Shopping\" / \"Fall-Back\"** → Product feed campaigns. High impressions with low conversion may signal feed quality issues.\n- **Market codes** (e.g. \"NL\", \"BE\", emoji flags) → Geographic targeting. Compare markets separately rather than blending.\n- **\"ABO\" vs \"CBO\"** → Facebook ad set budget optimization vs campaign budget optimization. ABO gives more granular control; CBO lets Meta auto-allocate.\n\nUse these signals to assign funnel context rather than judging all campaigns by a single ROAS bar.\n\n## Interpretation heuristics\n\nThese are contextual guidelines, not fixed thresholds -- actual values vary by industry, product, and market.\n\n- **High CPA for TOFU campaigns**: expected. TOFU generates awareness, not immediate conversions.\n- **High CPA for BOFU campaigns**: concerning. These should be your most efficient converters.\n- **Falling CTR with stable audience and offer**: likely creative fatigue. Suggest testing new creatives before cutting budget.\n- **High ROAS on branded search**: expected but not scalable. Branded search captures existing demand; it does not create new demand.\n- **Zero event_value or number_of_events across all campaigns**: likely a data issue, not a performance issue. Warn the user and suggest checking data completeness before drawing conclusions.\n- **ROAS looks great but spend is tiny**: the campaign may not be scalable. Efficiency at low spend does not guarantee efficiency at higher spend.\n\n## Critical budget anti-pattern: do not shift TOF budget to BOF\n\nWhen BOFU campaigns show much higher ROAS than TOFU campaigns, it is tempting to recommend moving budget from top-of-funnel to bottom-of-funnel. Do not do this. BOFU campaigns convert users that TOFU campaigns first made aware of the brand. Cutting TOFU starves the funnel that BOFU depends on, leading to declining performance over time even though the short-term ROAS looks great.\n\nInstead, suggest optimizing within TOFU (better creatives, better audiences, reallocating between TOFU campaigns) or consult `references/budget-optimization.md` for deeper budget strategy guidance.\n\n## MER (Marketing Efficiency Ratio)\n\nMER is calculated as total revenue divided by total marketing spend. Billy Grace strongly discourages using MER for decision-making because it creates a perverse incentive: cutting marketing spend directly improves MER, making it look like performance improved when in reality you are starving the funnel. Short-term gains from spend cuts mask long-term damage to pipeline and revenue.\n\nIf a user asks about MER, explain this dynamic and suggest ROAS at the channel or campaign level as a more actionable alternative.\n\n## Email, CRM, and owned channels\n\nChannels like Klaviyo, email newsletters, loyalty programs, and direct traffic often appear in Billy Grace data with zero spend. They represent **demand capture and retention**, not paid acquisition.\n\n- **Do not compare their \"ROAS\" to paid channels.** With zero spend, ROAS is undefined -- these channels are not competing on the same playing field as Meta or Google.\n- **High revenue from email/CRM is a sign of healthy retention**, not proof that paid is underperforming. Paid acquisition creates the customer base that email then nurtures and reconverts.\n- **When email revenue dominates**, highlight it as a strength but frame paid channels in terms of their **marginal contribution**: are they bringing in new customers that email can later retain?\n- **Klaviyo flows vs campaigns**: automated flows (welcome series, cart abandonment, winback) are always-on retention engines. One-off campaigns (newsletters, promotions) are demand spikes. Both can show up as separate `campaign_name` values within the `klaviyo` source.\n\n## Incomplete data detection\n\nBefore analyzing results, check for signs of incomplete data:\n\n- If `event_value` and `number_of_events` are zero across all campaigns for recent dates, the data pipeline may have a gap. Do not present zero-conversion data as real performance -- flag it and ask the user to verify.\n- If a specific channel suddenly shows zero conversions while others look normal, that channel's integration may have an issue.\n\nPresent these as observations, not conclusions, and suggest the user investigate further.\n\n## Result presentation guidance\n\nTailor output format to the analysis type:\n\n- **Comparisons** (channels, campaigns, time periods): use tables for side-by-side readability.\n- **Overviews** (total performance summary): use a brief narrative with key numbers highlighted.\n- **Drill-downs** (investigating a specific issue): lead with the finding, then show supporting data.\n- **Trends** (daily/weekly performance over time): describe the trajectory and highlight inflection points.\n\n## Communication style\n\nFrame all advice as hypotheses and experiments, not directives. Marketing is complex and context-dependent -- what works for one business may not work for another.\n\n**Preferred phrasing**:\n- \"The data suggests...\"\n- \"It could be worth testing...\"\n- \"If this pattern continues, you might want to consider...\"\n- \"Given the current data, it is likely that...\"\n\n**Avoid**:\n- \"You must...\"\n- \"This is a waste of money.\"\n- \"Always do X.\"\n\nAcknowledge uncertainty and trade-offs. When the user asks for a definitive recommendation, explain the reasoning and caveats rather than giving a bare instruction.\n\nFor deeper guidance on budget optimization strategy, consult `references/budget-optimization.md`.\n\n## Cross-skill references\n\n- Use the **billy-grace-data-retrieval** skill to fetch data through the MCP tools before applying this analysis guidance.\n- When the analysis involves choosing or interpreting attribution settings, consult the **billy-grace-attribution** skill.\n"
}