Marketing Swarm

View saved version →

---
name: budget-media-allocation
description: Use when deciding how to distribute paid-media budget across campaigns, audiences, geographies, or platforms, including cross-platform comparisons and attention-cost opportunities.
---

# Budget and Media Allocation

Compare marginal opportunity, not just headline ROAS.

## Required framing

Establish:

- total budget and time horizon
- objective and primary KPI
- constraints and minimum viable spend per campaign/platform
- current allocations
- comparable performance windows
- whether metrics are platform-attributed or experimentally validated

## Analysis

### Normalize the comparison

Do not compare platforms as if attribution, auction dynamics, conversion windows, and funnel roles were identical. Note differences in intent, reach, frequency, conversion lag, and measurement.

### Estimate marginal value

Where data permits, inspect how performance changes as spend changes. Prefer spend-response evidence over a single average ROAS/CPA.

Use signals such as:

- CPM and qualified reach
- CTR and click quality
- CVR and CPA
- revenue/value and margin-adjusted return
- saturation/frequency
- impression share or lost opportunity
- recent budget-response behavior
- creative capacity and fatigue

Do not call lower CPM an arbitrage opportunity unless downstream quality makes the inventory economically useful.

### Build allocation scenarios

Provide at least three when the user wants a decision:

- **protect**: prioritize stability and proven efficiency
- **balanced**: shift limited budget toward stronger marginal opportunities
- **explore**: reserve controlled spend for uncertain but promising opportunities

For each scenario state allocation, rationale, main risk, and measurement plan.

### Cross-platform rule

Treat platform-reported conversions as a measurement input, not a common currency. If platform overlap or attribution conflict could reverse the decision, route to `causal-attribution` before recommending a large shift.

## Output contract

Return:

- current allocation diagnosis
- opportunities and constraints
- scenario table
- recommended scenario with confidence
- expected directional impact or range, only when data supports it
- guardrails and rollback/stop conditions
- measurement needed to learn from the shift

Do not claim a precise future ROAS from sparse historical averages.

Referenced files: 1

View saved version →

---
name: campaign-diagnostics
description: Use when paid-media performance changed, spend looks abnormal, delivery or pacing is off, or the user wants an account/campaign health diagnosis before choosing tactics.
---

# Campaign Diagnostics

Diagnose before prescribing tactics. Separate arithmetic changes from causal explanations.

## Inputs

Prefer campaign-level or lower-grain data with current and comparison periods. Useful fields include spend, impressions, reach, frequency, CPM, clicks, CTR, CPC, landing-page views, conversions, CVR, CPA, revenue/value, ROAS, budget, delivery status, audience size, attribution window, and creative/ad identifiers.

## Diagnostic sequence

### 1. Validate comparability

Check:

- same metric definitions and attribution settings
- same or comparable date length and day-of-week mix
- reporting lag and conversion latency
- major promotions, stock, price, website, tracking, or offer changes
- campaign structure or learning-phase changes

### 2. Decompose the KPI

For a CPA problem, inspect the chain:

`CPA = CPC / CVR`, while `CPC` is influenced by CPM and CTR.

For ROAS, inspect revenue/value per conversion as well as acquisition cost. A falling ROAS can come from traffic cost, conversion efficiency, basket/value changes, attribution shifts, or a mix of them.

Use Python for deterministic calculations when the host exposes it and the data volume warrants execution.

### 3. Detect risk patterns

Flag only when supported by data:

- overspend or underspend versus expected pacing
- abrupt CPM/CPC movement
- CTR or CVR deterioration
- high frequency paired with creative performance decay
- suspicious click/conversion spikes
- placement or geography concentration changes
- budget fragmentation or learning resets
- tracking gaps or metric discontinuities

Classify severity as `low`, `medium`, `high`, or `critical` based on magnitude, confidence, and business exposure. Do not label fraud from weak signals alone.

### 4. Rank explanations

For each explanation include:

- evidence supporting it
- evidence contradicting it
- confidence
- cheapest discriminating check

Avoid the common failure mode of converting correlation into a single-cause story.

## Output contract

Return:

1. health summary
2. metric decomposition
3. anomalies and severity
4. ranked explanations
5. immediate protections, if any
6. next checks/tests
7. data gaps

If there is a credible spend-loss condition, put the protective action first. A proposed pause, cap, exclusion, or budget change is still a recommendation until an authorized app executes it.

Referenced files: 1

View saved version →

---
name: causal-attribution
description: Use for attribution disputes, incrementality questions, causal claims, holdout or lift-test review, counterfactual analysis, and cases where platform-reported credit may not represent true business impact.
---

# Causal Attribution and Incrementality

Ask the causal question before choosing an attribution method.

## Start with the estimand

Define what the user is trying to know, for example:

- incremental conversions caused by a campaign
- incremental revenue from additional spend
- channel contribution versus organic/base demand
- effect of a creative or audience treatment
- likely result if a campaign were paused or budget changed

## Build a causal map

List exposure/treatment, outcome, important pre-treatment variables, plausible confounders, mediators, and colliders. Keep the map practical. The goal is to stop inappropriate adjustment and unsupported causal stories.

Common confounders can include seasonality, promotions, brand demand, geography, audience intent, inventory, price changes, CRM activity, and concurrent media.

## Evidence hierarchy

Prefer, where feasible:

1. randomized holdout / geo / audience experiment
2. credible quasi-experimental design
3. calibrated observational model with explicit assumptions
4. platform attribution or path models for descriptive credit

Do not treat multi-touch attribution as incrementality by default.

## Incrementality review

When test/control data is supplied, check:

- randomization or assignment mechanism
- contamination and spillover
- sample ratio issues
- pre-period balance
- outcome definition
- conversion lag
- statistical uncertainty
- business significance, not only p-values

Use Python for calculations when execution is available and the test requires it.

## Counterfactual questions

For what-if analysis, state the assumptions needed to estimate the unobserved alternative. If those assumptions are not credible, return a range or an experiment design instead of a false answer.

## Output contract

Return:

- causal question
- measurement design or current evidence type
- major confounders/bias risks
- what can be claimed
- what cannot be claimed
- incrementality estimate/range when supported
- recommended next experiment or validation

Use language such as `associated with`, `consistent with`, and `caused by` deliberately. They are not interchangeable.

Referenced files: 1

View saved version →

---
name: creative-fatigue-mutation
description: Use when an ad may be fatiguing, the user needs refresh timing, or they want new variants derived from proven creative elements while preserving a clear testing logic.
---

# Creative Fatigue and Mutation

Distinguish fatigue from other reasons a creative slows down, then plan refreshes that teach something.

## Fatigue assessment

Useful evidence includes launch date, spend/exposure over time, reach, frequency, CPM, CTR, CPC, CVR, CPA/ROAS, audience size, placement mix, and creative rotation history.

Signals can include:

- rising frequency with falling response
- CTR decay after stable delivery
- worsening CPA/ROAS without a corresponding funnel/site change
- repeated exposure concentrated in a finite audience
- performance recovery after refresh

Do not infer fatigue from age alone. A creative can be old and still incremental, or new and already weak.

Classify state as:

- `fresh`
- `performing`
- `early-fatigue`
- `fatigued`
- `exhausted`
- `uncertain`

Use `uncertain` when attribution, audience, auction, or site changes could explain the decay.

## Mutation logic

Start from the creative hypothesis, not random cosmetic changes. Preserve one proven element and vary one meaningful dimension when possible.

Mutation dimensions can include:

- hook
- angle / problem framing
- proof mechanism
- offer framing
- demo sequence
- CTA
- visual opening
- copy structure
- format / duration

Use crossover only when two parent creatives have independently supported strengths and the combination has a clear hypothesis.

## Refresh plan

For each proposed variant include:

- what stays constant
- what changes
- why it changes
- intended audience response
- success metric
- minimum evidence needed before judging

## Output contract

Return fatigue diagnosis, evidence, alternative explanations, refresh priority, and a test-ready variant matrix. Do not promise a remaining lifespan in days unless the time-series evidence supports that estimate.

Referenced files: 1

View saved version →

---
name: creative-genome-analysis
description: Use to analyze one or more ads or creative variants, identify the message and execution patterns associated with performance, and turn winners into testable creative hypotheses without copying them blindly.
---

# Creative Genome Analysis

Break creative into analyzable components, then relate those components to audience response and performance evidence.

## Creative representation

For each asset, capture only what is actually observable or provided:

- hook: question, claim, contrast, demonstration, story, statistic, direct offer, other
- audience/problem cue
- promise or desired outcome
- mechanism or reason-to-believe
- proof: demonstration, testimonial, data, social proof, authority, guarantee, none
- offer and price framing
- CTA
- visual opening / first-frame idea
- product visibility
- pacing and format
- copy length and density
- brand presence

Do not force every ad into a fixed taxonomy when the format does not fit.

## Performance linkage

When creative-level data exists, compare elements against relevant metrics. Avoid declaring an element a winner because it appears in one winning ad.

Look for:

- repeated patterns across multiple strong creatives
- interaction effects between message and format
- top-of-funnel attention versus downstream conversion quality
- changes after audience, placement, or spend shifts
- sample size and exposure imbalance

Classify findings as:

- **observed pattern**
- **plausible mechanism**
- **untested hypothesis**

## Build the next test

Turn analysis into a controlled matrix. Prefer changing one major hypothesis dimension at a time unless the goal is exploratory concept testing.

Examples of test dimensions:

- hook angle
- proof format
- offer framing
- demo versus testimonial
- product-first versus problem-first opening
- CTA specificity

## Output contract

Return:

1. creative map
2. patterns associated with stronger/weaker outcomes
3. mechanisms that may explain them
4. confidence and confounders
5. next creative hypotheses
6. test matrix with success metric

Do not recommend cloning superficial styling when the evidence points to the underlying proposition or proof structure instead.

Referenced files: 1

View saved version →

---
name: decision-quality-gate
description: Use before finalizing high-impact marketing recommendations or whenever multiple analyses disagree, evidence is weak, causal language may be overstated, or a live campaign change is being considered.
---

# Decision Quality Gate

Review the recommendation, not just the prose.

## Gate checks

### Evidence integrity

- Are stated observations present in the supplied or retrieved data?
- Are calculations reproducible?
- Are time windows and metric definitions compatible?
- Are missing data and reporting lag acknowledged?

### Causal discipline

- Does the recommendation claim causality from correlation?
- Could attribution overlap or confounding reverse the conclusion?
- Is a modeled forecast being presented as observed fact?

### Decision economics

- Does the action align with the business objective rather than a proxy metric?
- Are margin, volume, capacity, and opportunity cost relevant?
- Is the proposed action material enough to matter but bounded enough to learn safely?

### Risk and reversibility

Classify the proposal:

- low-risk / reversible
- moderate-risk / reversible with monitoring
- high-impact / requires stronger evidence or staged rollout
- blocked / evidence or permissions insufficient

### Execution boundary

A plan is not an executed change. If the host provides a compatible write-capable app and the user explicitly authorizes the mutation, restate the exact change set before execution. Otherwise return a ready-to-execute plan only.

## Scorecard

Score each dimension `pass`, `warn`, or `fail`:

- evidence
- measurement
- causal claim
- expected economics
- risk
- reversibility
- authorization

Any `fail` on evidence, authorization, or a material causal claim blocks live execution.

## Output contract

Return gate result, warnings, blocked claims/actions, revised recommendation, and the minimum additional evidence needed to clear the gate.

Referenced files: 1

View saved version →

---
name: host-workspace-operator
description: Use when a Marketing Swarm workflow needs to inspect, search, modify, or verify files in the host workspace using the safest native tools available.
---

# Host Workspace Operator

Use workspace tools supplied by the current ChatGPT/Codex host instead of pretending the Plugin owns a filesystem API.

Tool names differ by surface. Route by capability, not by a hard-coded tool name. Typical capabilities include read, list, search, grep, write, patch, shell, and python.

## Capability order

Prefer the narrowest operation that can answer the task:

1. **read**: open a known file or exact range when the path is known.
2. **list**: enumerate a directory or workspace scope when filenames are unknown.
3. **search**: use semantic/content search when the user asks a broad question or exact wording is uncertain.
4. **grep**: use exact text or regex search when the term, symbol, field, or pattern is known.
5. **patch**: make a focused edit to an existing file when a patch-capable host tool exists.
6. **write**: create or replace a file only when the requested workflow requires a mutation.
7. **shell**: run repository commands when file tools are insufficient and command execution is appropriate.
8. **python**: use host-native Python for deterministic parsing, transformations, hashing, package inspection, or verification.

Do not use shell or Python just to imitate a safer read/search/file operation that the host already provides.

## Read-only first

Treat read, list, search, and grep as the default discovery phase. Inspect enough evidence to understand the current state before mutation.

For campaign-export or report work:

- inspect the file shape before transforming it
- preserve original files unless the user requested an edit
- prefer exact reads after search locates the relevant material
- distinguish raw source data from generated analysis artifacts

## Mutation boundary

Write, patch, delete, move, rename, format, or command-based modification are mutation operations.

Before mutation:

- confirm the user requested or clearly authorized the change
- preserve unrelated work
- prefer a focused patch over full-file replacement
- never write secrets into reports, examples, manifests, or release artifacts

After mutation, read the changed area back when practical, run the relevant verifier when available, and report the exact files changed.

## If a tool is unavailable

Do not invent a replacement tool name, claim an operation occurred, or imply the Plugin grants filesystem permissions. Use another available capability only when it preserves the task semantics; otherwise mark the dependent result unverified.

Referenced files: 1

View saved version →

---
name: marketing-memory
description: Use when the user has prior campaign results, experiments, creative history, or benchmarks and wants to find comparable past evidence, reusable patterns, or lessons relevant to a current decision.
---

# Marketing Memory

Use the user's own historical evidence as context without turning anecdotes into universal rules.

## Retrieve by decision relevance

Match past cases using dimensions that matter to the current question, such as:

- platform and campaign objective
- market / geography
- product, price, margin, or offer
- audience intent and size
- funnel stage
- budget scale
- seasonality / promotion state
- creative format and message angle
- attribution setup
- measurement quality

Do not rank cases by superficial similarity when economically important conditions differ.

## Convert history into evidence

For each relevant case capture:

- context
- action or treatment
- observed result
- measurement quality
- what changed at the same time
- lesson
- transferability to the current case

Distinguish:

- repeated pattern
- single precedent
- failed test
- unresolved case

## Benchmark rule

Use external benchmarks only when the user explicitly provides them or the host can retrieve current credible sources. Never invent industry averages. User-specific historical baselines are often more useful than generic benchmarks.

## Output contract

Return the most relevant prior cases, why they match, why they may not transfer, the lesson to reuse, and the current hypothesis they support or weaken.

When no sufficiently comparable history exists, say so and route to `scenario-simulation` or an experiment rather than forcing a memory match.

Referenced files: 1

View saved version →

---
name: marketing-swarm-router
description: Use for broad or multi-part paid-media questions that need routing across campaign diagnosis, budget allocation, creative analysis, fatigue planning, simulation, attribution, historical evidence, and quality review.
---

# Marketing Swarm Router

Route a marketing question to the smallest useful set of specialist Skills. Do not answer every request with every Skill.

## First classify the job

Identify one or more of these jobs:

- **diagnose**: performance drop, pacing, spend anomaly, account health, delivery instability -> `campaign-diagnostics`
- **allocate**: budget split, platform mix, marginal spend, media opportunity -> `budget-media-allocation`
- **decode creative**: understand why ads differ, identify hook/promise/proof/CTA patterns -> `creative-genome-analysis`
- **refresh creative**: fatigue, decay, rotation, next variants, test matrix -> `creative-fatigue-mutation`
- **forecast**: what-if, sensitivity, expected ranges, budget scenarios -> `scenario-simulation`
- **test causality**: attribution, incrementality, lift, confounders, counterfactual claims -> `causal-attribution`
- **compare history**: past campaigns, benchmarks from supplied history, reusable lessons -> `marketing-memory`
- **review decision**: check evidence quality, contradictions, risk, overclaiming -> `decision-quality-gate`

## Evidence inventory

Before routing, identify what is actually available:

- business objective and primary KPI
- platform/account/campaign/ad set/creative grain
- reporting period and comparison period
- spend, impressions, clicks, conversions, revenue or value
- attribution window/model where relevant
- creative identifiers and launch dates where relevant
- prior tests, holdouts, experiments, or historical campaigns
- known constraints: budget floors, inventory, geography, policy, learning phase, margin, capacity

Do not block on every missing field. Continue with the evidence available and state which missing fields materially lower confidence.

## Routing principles

1. Use the narrowest specialist that can solve the job.
2. Parallelize independent analyses when the host supports it, but reconcile them before answering.
3. Do not treat platform-reported attribution as causal proof.
4. Do not treat a forecast as observed evidence.
5. Do not recommend a budget shift without checking whether the apparent winner is affected by volume, learning, attribution, inventory, or creative fatigue.
6. For high-impact decisions, invoke `decision-quality-gate` before finalizing.

## Standard answer frame

For multi-Skill work, return:

- **What changed**: the observed pattern
- **Most likely explanations**: ranked, with evidence for/against
- **What is uncertain**: missing evidence or confounders
- **What to do next**: prioritized actions/tests
- **Decision thresholds**: what result would make you continue, stop, scale, or reverse

If a compatible host app can make campaign changes, analysis and execution remain separate. Never turn a recommendation into a live mutation without explicit user authorization for the material change.

Referenced files: 1

View saved version →

---
name: sandbox-python-executor
description: Use when Marketing Swarm needs deterministic metric calculation, tabular analysis, simulation, statistical checks, file processing, or verification that should actually run with host-native Python instead of relying on unverified mental arithmetic.
---

# Sandbox Python Executor

Use the host's own Python execution capability to produce evidence, not just code suggestions.

This Skill does not create a remote runtime and does not declare an MCP dependency. Tool availability belongs to the host.

## Use Python for

- campaign metric calculation across many rows
- period comparisons and decompositions
- scenario and sensitivity analysis
- bootstrap or Monte Carlo calculations when justified
- incrementality/lift statistics
- CSV/JSON parsing and data validation
- deterministic charts/tables when requested
- archive/package verification during Plugin maintenance

## Execution rule

1. Actually execute the calculation when Python is available and the answer depends on it.
2. Keep source campaign files read-only unless the user requested transformation.
3. State assumptions and data-cleaning choices that affect the result.
4. Do not assume sandbox internet access.
5. Do not expose tokens, credentials, or unrelated files.
6. Preserve generated artifacts the user needs and return the host-provided file reference/path when available.

## Evidence

Report enough to distinguish an executed calculation from an estimate: operation, important inputs/filters, pass/fail or result summary, generated file when applicable, and warnings.

## If Python is unavailable

Do not claim execution occurred. Continue with static reasoning only when appropriate and mark execution-dependent calculations as unverified.

Referenced files: 1

View saved version →

---
name: scenario-simulation
description: Use for campaign what-if questions, budget or KPI forecasts, sensitivity analysis, and decision ranges where deterministic or probabilistic scenarios are more useful than a single point estimate.
---

# Scenario Simulation

Use simulation to expose decision ranges and sensitivity. Do not decorate weak assumptions with false precision.

## Choose the method

Use the simplest defensible method:

- deterministic scenario table for direct arithmetic changes
- sensitivity analysis when one or more assumptions drive the result
- bootstrap/resampling when representative historical observations are available
- Monte Carlo only when probability distributions or defensible uncertainty ranges can be specified

Use host-native Python when available for non-trivial calculations. Report the executed method and assumptions.

## Define the model

Specify:

- target metric and horizon
- starting state
- controllable inputs
- uncertain inputs
- constraints
- relationship assumptions
- number of simulations, if applicable

Do not silently assume that CPA, ROAS, CVR, or CPM remains constant as spend changes. If a constant-rate scenario is useful as a baseline, label it explicitly.

## Scenario set

Typically compare:

- base case
- conservative case
- expected/planning case
- upside case

For budget decisions, include the current allocation as a control scenario.

## Sensitivity

Identify which assumptions have the largest influence on the decision. If a small change in one uncertain parameter flips the recommendation, the answer should emphasize measurement rather than confidence.

## Output contract

Return:

- model and assumptions
- scenario results or distributions
- sensitivity drivers
- decision boundary
- what the model cannot infer
- next measurement that would reduce uncertainty most

A simulated result is not evidence that the future will occur. Keep observed data and modeled outcomes separate.

Referenced files: 1