Media routing planner

Media Routing Planner

Engineer optimal routes for budget to move from investment to business impact — using the logic of logistics routing where budget is cargo, channels are routes, platforms are carriers, audiences are destinations, and KPIs are delivery outcomes.

How This Skill Orchestrates

This is the media intelligence layer of the OS. It doesn't create generic media plans — it solves a constrained optimization problem:

1. Script execution (scripts/media_optimizer.py): Constrained optimization with Hill saturation curves per channel. Generates 4 scenario variants (Conservative, Balanced, Growth, Efficiency), detects 8 waste patterns, scores routes on speed/scale/incrementality/measurement
2. Reference lookup (references/channel_benchmarks.md): Channel-level benchmarks (14 channels, 8 scoring dimensions), funnel allocation frameworks, waste detection patterns, optimization methodology
3. Upstream context (Claude): Pull MMM parameters from mmm-modeling, scope validation from scope-audit, margin data from margin-simulation, capacity from fte-capacity-sizing
4. Web search (Claude): Search for current CPM/CPC benchmarks by platform and industry when user specifies market context
5. Visual output (Visualizer): Route allocation dashboard + funnel waterfall + scenario comparison + interactive budget slider

Model decision: Constrained nonlinear optimization (scipy SLSQP / greedy fallback) — this IS a mathematical optimization problem. We have an objective function (maximize total response), constraints (budget, floors, ceilings), and a parametric response model (Hill curves per channel). Not ML — no training data needed. Not heuristics — we solve the actual optimization. Read references/channel_benchmarks.md → "Optimization Methodology" for the full rationale.

Mandatory Benchmark Search Protocol

BEFORE running the optimizer or producing any output, Claude MUST search for current public benchmarks. The script's built-in benchmarks are cross-industry defaults from 2025 — they are fallbacks, not primary data.

Search sequence (execute in order)

1. When the user specifies [COUNTRY]: Search for "digital advertising benchmarks [COUNTRY] [YEAR]" — CPM, CPC, CPA vary dramatically by market (e.g., Meta CPM in US = $23, in Mexico = $4.20, in India = $2.60 per AdAmigo 2026 data)
2. When the user specifies [INDUSTRY]: Search for "[INDUSTRY] advertising benchmarks CPM CPC CPA ROAS [YEAR]" — use Triple Whale, WordStream, Pixis, or platform-published data
3. When the user specifies [CHANNEL/PLATFORM]: Search for "[PLATFORM] ads benchmarks [INDUSTRY] [YEAR]" — Meta, Google, TikTok, LinkedIn all publish or have third-party benchmarks
4. When the user specifies [BRAND]: Search for "[BRAND] advertising spend media mix" and "[BRAND] [INDUSTRY] market share Kantar Nielsen" — contextualize vs. competitive set
5. Always search for: "Nielsen ad intel [INDUSTRY] [COUNTRY]" OR "Kantar Worldpanel [CATEGORY] [COUNTRY]" for market-level context

How to use search results

• Override the script's default benchmarks with searched data via the channel_overrides and historical_roas config parameters
• Cite the source in the output: "Meta CPM at $4.20 for Mexico Tier 3 market (AdAmigo 2026)" not just "$4.20"
• If no country-specific data is found, use Tier-based estimates: Tier 1 (US/UK/AU) → highest CPMs, Tier 2 (EU/UAE) → mid, Tier 3 (LATAM/APAC) → lowest
• Always note when using fallback benchmarks: "⚠️ Using cross-industry defaults — search for [INDUSTRY] [COUNTRY] benchmarks for more accurate data"

Key public benchmark sources

Source	What it covers	Search query pattern
Triple Whale	Meta + Google benchmarks by industry (18K+ brands)	"Triple Whale [platform] benchmarks [industry] [year]"
WordStream	Google Ads + Facebook Ads benchmarks by industry	"WordStream [platform] benchmarks [year]"
Nielsen Ad Intel	Ad spend by industry, channel share, SOV by country	"Nielsen ad intel [industry] [country]"
Kantar Worldpanel	Market share, brand penetration, purchase frequency	"Kantar Worldpanel [category] [country]"
Kantar BrandZ	Brand value, equity metrics	"Kantar BrandZ [brand] [year]"
eMarketer / EMARKETER	Digital ad spend forecasts, channel benchmarks	"eMarketer [channel] ad spend [country] [year]"
WARC	Marketing effectiveness, media ROI benchmarks	"WARC media effectiveness [industry] [year]"
Statista	Market size, industry data, ad spend by country	"Statista digital advertising [country] [year]"
Pixis	Google Ads benchmarks by industry (CPM, CPC, CTR)	"Pixis Google advertising benchmarks [industry]"
AdAmigo	Meta Ads CPM/CPC by country (45 countries)	"AdAmigo Meta CPM [country] [year]"
Platform published	Official benchmarks from Meta, Google, TikTok, LinkedIn	"[platform] business benchmarks [industry]"
Varos	Real-time D2C benchmark comparisons	"Varos benchmark [platform] [industry]"

2025-2026 verified reference points (from search)

These are verified data points from the search above — use as calibration anchors:

Meta Ads (2025-2026):

• Global median CPM: $13.48 (Triple Whale 2025)
• US CPM: $23.00 | Mexico CPM: ~$4.20 | Brazil CPM: ~$4.20 | India CPM: $2.60 (AdAmigo 2026)
• Median CPA: $38.17 | Median ROAS: 1.93 | Median CTR: 2.19% (Triple Whale 2025)
• Automotive CPA improved -6.04% YoY (Triple Whale 2025)
• FB avg CPC: $0.62 (WordStream 2025) | IG feed CPC: $3.35 | IG Stories CPC: $1.83

Google Ads (2025-2026):

• Median CPA: $23.74 (+12.35% YoY) | Median CPM: $12.79 (+10.01% YoY) (Triple Whale 2025)
• Median ROAS: 3.68 (-10.03% YoY) | Median CTR: improved +7.49% (Triple Whale 2025)
• Automotive CPM: $14.30 | CPC: $0.92 (Pixis 2025)
• Healthcare CPM: $36.82 (highest) | Display CPM: $2.54 (lowest) (Pixis 2025)
• Search avg CPA: $48.96 (Coupler.io 2025)

TikTok (2025-2026):

• CPM: $4-8 (lowest major platform) | CPA for D2C: $12-28 (Jonas Agency 2026)
• Spark Ads deliver 30-50% lower CPA vs standard In-Feed (TikTok Creative Center)

LinkedIn (2025-2026):

• CPM: $20-45 | Lead Gen Form CVR: 13% vs 2.5% external (LinkedIn B2B Report 2025)
• Q1 pipeline ROI: 2.44x (HockeyStack, $28M spend analysis)

Platform CPM summary (2026): TikTok $4-8 < X $5-10 < Meta $8-14 < YouTube $10-18 < LinkedIn $20-45 (Jonas Agency 2026)

Quick Reference

Resource	Purpose	Usage
scripts/media_optimizer.py	Constrained optimizer — Hill curves per channel, 4 scenarios (Conservative/Balanced/Growth/Efficiency), 8 waste detection patterns, route quality scoring, funnel allocation, 14 channel benchmarks	python media_optimizer.py --input plan.json --output routes.json
scripts/saturation_checker.py	Standalone diagnostic — evaluates an EXISTING media plan (not from optimizer) for saturation %, frequency over-cap, and waste per channel. Useful for auditing client's current plan	python saturation_checker.py --input current_plan.json --output diagnosis.json
references/channel_benchmarks.md	14-channel benchmark table (CPM/CPC/CPA/ROAS + speed/scale/incrementality/measurement), funnel frameworks by objective, waste patterns, Hill curve calibration guide, upstream/downstream integration	Read for benchmarks and methodology
references/saturation_frequency_rules.md	Frequency caps by channel (weekly/monthly), creative fatigue detection thresholds, saturation zone definitions (growth → waste), frequency × saturation decision matrix	Read for frequency management and rotation cadence
references/reallocation_triggers.md	11 specific reallocation triggers with numeric thresholds and if/then logic, weekly/monthly/daily cadences, escalation paths, guardrails, worked example	Read for in-flight optimization rules

How to Use the Script

import sys
sys.path.insert(0, "<skill-path>/scripts")
from media_optimizer import MediaRoutingOptimizer

config = {
    "client_name": "AcmeAuto MX",
    "business_objective": "Increase Q3 sales by 15%",
    "campaign_objective": "Drive qualified traffic to dealers",
    "total_budget": 200000,
    "period": "Q3 2026 (3 months)",
    "currency": "USD",
    "objective_type": "conversion",  # awareness|consideration|conversion|retention|full_funnel|growth
    "channels": ["search", "social_meta", "social_tiktok", "video_youtube", "display_programmatic"],
    "excluded_channels": ["tv_linear"],  # Too expensive for budget
    "floors": {"search": 30000},  # Minimum search spend
    "ceilings": {"display_programmatic": 40000},  # Cap display
    "historical_roas": {"search": 6.2, "social_meta": 3.8},  # Override benchmarks
}

opt = MediaRoutingOptimizer(config)
result = opt.optimize()
# result.scenarios → 4 allocation variants
# result.waste_flags → detected waste patterns
# result.recommended_scenario → the best fit for the objective

If the user has run mmm-modeling, use those Hill curve parameters instead of benchmarks — this dramatically improves allocation accuracy.

Calibration note: Default benchmarks are cross-industry averages. Always prefer historical client data when available. The optimizer uses a greedy marginal-ROAS allocation by default; when scipy is installed, it uses SLSQP for true constrained optimization.

Process

Step 1 — Define the Business Outcome

What is the media investment trying to achieve? Not "run social ads" but "drive 2,000 qualified dealer visits at CPA ≤ $100." Translate the business objective into a campaign objective with a measurable KPI.

Step 2 — Translate Into Media Jobs

Map the objective to media jobs: demand creation, demand capture, conversion, retention, reactivation, traffic, brand building, retail activation. Each job maps to a funnel stage.

Step 3 — Map Budget as Cargo

The total budget is the cargo to route. Break it down by period (monthly, weekly) and identify any pre-committed spend (always-on search, fixed sponsorships).

Step 4 — Map Channels as Routes

Identify available channels. For each, assess: cost structure (CPM/CPC/CPA), speed to impact, scale potential, incrementality, measurement quality, creative requirements, operational complexity. Use benchmarks from the reference as defaults; override with client data.

Step 5 — Identify Constraints

Before optimizing, map: budget floors (minimum per channel), ceilings (maximum), minimum viable spend thresholds, creative readiness per channel, audience size limits, frequency caps, platform restrictions, landing page readiness, legal/brand safety constraints.

Step 6 — Run the Optimizer

Execute the script to generate 4 scenarios. Each uses different weighting profiles for the route quality dimensions. The optimizer respects all constraints, applies Hill curve saturation per channel, and detects waste patterns.

Step 7 — Detect Waste

Review the 8 waste patterns: over-saturation, capture-without-demand, audience overlap, over-frequency, low measurement, weak conversion environment, platform-reported inflation, channel duplication. Each flag includes estimated waste % and a fix.

Step 8 — Build Funnel Allocation

Map the allocation to the funnel: upper (brand/reach) → mid (consideration/education) → capture (conversion/action) → lower (retention/CRM). Compare against the objective-specific funnel weights from the reference.

Step 9 — Recommend and Explain

Select the recommended scenario based on objective type. Explain the trade-offs between scenarios. List operational dependencies (creative, tracking, CRM, landing pages).

Step 10 — Define Optimization Rules

Provide rules for when to reallocate during the campaign: performance thresholds, saturation triggers, weekly and monthly review cadences.

Output Format

Produce in TWO forms: inline visual dashboard (Visualizer) and structured markdown report.

Visual Dashboard (Primary)

Render the media routing dashboard as an inline HTML widget:

• A header with client, objective, total budget, and recommended scenario badge
• A route allocation table — one row per channel: label, funnel stage, budget $, budget %, projected ROAS, saturation %, speed, risk score. Color-coded by funnel stage (upper = purple, mid = teal, capture = coral, lower = green)
• A funnel waterfall — horizontal stacked bar showing upper/mid/capture/lower allocation percentages
• A scenario comparison grid — 4 cards (Conservative/Balanced/Growth/Efficiency) showing blended ROAS, channel count, and funnel split. Recommended card has accent border
• A waste flags section — each flag as a row with type badge, estimated waste %, and fix
• An action footer with sendPrompt() buttons:
  • "Run campaign QA for this media plan" → campaign-launch-qa
  • "Plan creative assets for these channels" → creative-supply-planner
  • "Set up measurement for this allocation" → measurement-incrementality

Use CSS variables for light/dark mode.

Markdown Report (Secondary)

## 🗺️ MEDIA ROUTING PLAN — [Client] — [Period]

### Executive decision
[1-2 sentences: recommended scenario, blended ROAS, key trade-off]

### Business objective
[What the route is engineered to achieve]

### Routing logic
[How money flows through the funnel — demand creation feeds capture]

### Route allocation table
| Channel | Funnel | Job | Budget | % | ROAS | Saturation | Speed | Risk |
[One row per channel, sorted by budget desc]

### Funnel allocation
| Stage | Role | Channels | Budget % |
[Upper / Mid / Capture / Lower]

### Scenario comparison
| Scenario | ROAS | Channels | Funnel split | Best for |
[4 scenarios]

### Waste / leakage flags
[Each flag: type, channel, estimated waste %, fix]

### Dependencies
[Numbered list: creative, tracking, CRM, landing pages, approvals]

### Optimization rules
[When to reallocate: thresholds, triggers, cadences]

### Recommendation
[Clear decision with rationale and financial implication]

Examples

Example 1 — E-commerce conversion: User: "$150K budget for Q3, e-commerce, goal is 3,000 purchases at CPA ≤ $50." → Efficiency scenario recommended: search 35%, Meta 25%, retail media 20%, CRM 10%, TikTok 10%. Blended ROAS 4.8x. 1 waste flag (display cut — low incrementality).

Example 2 — Brand awareness: User: "Automotive brand, $500K for a 6-month awareness campaign targeting 25-45 adults in Mexico." → Growth scenario: YouTube 25%, CTV 20%, Meta 20%, TikTok 15%, OOH 10%, programmatic 10%. Focus on reach and frequency. 2 waste flags (CTV measurement, OOH measurement).

Example 3 — Budget reallocation: User: "ROAS dropped from 4.2x to 3.1x. Current split is 60% search, 30% Meta, 10% display. Budget $80K/mo." → Diagnosis: search over-saturated (75%), demand pool shrinking. Recommended: reduce search to 40%, increase TikTok to 15%, add YouTube at 15%, maintain Meta at 25%, cut display. Projected ROAS recovery to 3.8x.

Skill Chaining

Direction	Skill	Connection
Upstream	scope-audit	Validates media scope is in SOW
Upstream	fte-capacity-sizing	Confirms team can operate allocated channels
Upstream	margin-simulation	Validates margin at media fee level
Upstream	mmm-modeling	Provides calibrated Hill curve parameters
Downstream	campaign-launch-qa	Validates readiness per allocated channel
Downstream	creative-supply-planner	Defines creative needs per channel
Downstream	measurement-incrementality	Defines what to measure per route
Downstream	weekly-control-tower	Provides budget pacing baseline
Downstream	executive-growth-memo	Frames routing decision for leadership
Downstream	media-procurement-benchmark	Validates rates and terms per carrier