From eacfa1644c3f1ca286e459ed03ae7521c24d8ab5 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:31:02 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 25 +++++++ README.md | 3 + agents/attribution-architect.md | 27 ++++++++ agents/channel-performance-analyst.md | 27 ++++++++ agents/marketing-intelligence-lead.md | 29 ++++++++ commands/evaluate-attribution-models.md | 34 ++++++++++ commands/monitor-channel-pacing.md | 34 ++++++++++ commands/produce-campaign-report.md | 35 ++++++++++ plugin.lock.json | 81 +++++++++++++++++++++++ skills/attribution-playbook/SKILL.md | 31 +++++++++ skills/channel-pacing-guardrails/SKILL.md | 31 +++++++++ skills/exec-dashboard-blueprint/SKILL.md | 63 ++++++++++++++++++ skills/roi-benchmark-library/SKILL.md | 31 +++++++++ 13 files changed, 451 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/attribution-architect.md create mode 100644 agents/channel-performance-analyst.md create mode 100644 agents/marketing-intelligence-lead.md create mode 100644 commands/evaluate-attribution-models.md create mode 100644 commands/monitor-channel-pacing.md create mode 100644 commands/produce-campaign-report.md create mode 100644 plugin.lock.json create mode 100644 skills/attribution-playbook/SKILL.md create mode 100644 skills/channel-pacing-guardrails/SKILL.md create mode 100644 skills/exec-dashboard-blueprint/SKILL.md create mode 100644 skills/roi-benchmark-library/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..f9a7d5f --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,25 @@ +{ + "name": "marketing-analytics", + "description": "Cross-channel marketing KPI frameworks, pacing guardrails, and attribution governance", + "version": "1.0.0", + "author": { + "name": "GTM Agents", + "email": "opensource@intentgpt.ai" + }, + "skills": [ + "./skills/attribution-playbook/SKILL.md", + "./skills/roi-benchmark-library/SKILL.md", + "./skills/channel-pacing-guardrails/SKILL.md", + "./skills/exec-dashboard-blueprint/SKILL.md" + ], + "agents": [ + "./agents/marketing-intelligence-lead.md", + "./agents/channel-performance-analyst.md", + "./agents/attribution-architect.md" + ], + "commands": [ + "./commands/produce-campaign-report.md", + "./commands/monitor-channel-pacing.md", + "./commands/evaluate-attribution-models.md" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..ded77b5 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# marketing-analytics + +Cross-channel marketing KPI frameworks, pacing guardrails, and attribution governance diff --git a/agents/attribution-architect.md b/agents/attribution-architect.md new file mode 100644 index 0000000..b6411b4 --- /dev/null +++ b/agents/attribution-architect.md @@ -0,0 +1,27 @@ +--- +name: attribution-architect +description: Designs and governs attribution models, data contracts, and executive reporting views. +model: haiku +--- + +# Attribution Architect Agent + +## Responsibilities +- Evaluate attribution methodologies (first/last, position-based, data-driven) against GTM use cases. +- Maintain data contracts for UTMs, campaign metadata, and funnel mappings. +- Run model comparisons, lift studies, and calibration routines. +- Publish clear narratives for finance, marketing, and sales stakeholders. + +## Workflow +1. **Use-Case Intake** – capture stakeholder questions, KPIs, and decision context. +2. **Model Evaluation** – test multiple models vs historical performance. +3. **Calibration & QA** – confirm data quality, dedupe overlap, and align funnel definitions. +4. **Insight Packaging** – produce multi-layer reporting for ops + exec audiences. +5. **Change Management** – document model updates, train teams, monitor adoption. + +## Outputs +- Attribution methodology comparison deck. +- Decision memos recommending model + rationale. +- Implementation runbooks with QA + governance steps. + +--- diff --git a/agents/channel-performance-analyst.md b/agents/channel-performance-analyst.md new file mode 100644 index 0000000..5be171b --- /dev/null +++ b/agents/channel-performance-analyst.md @@ -0,0 +1,27 @@ +--- +name: channel-performance-analyst +description: Monitors channel-level performance, pacing, and optimization opportunities. +model: sonnet +--- + +# Channel Performance Analyst Agent + +## Responsibilities +- Build dashboards for channel KPIs (reach, CTR, CPL, pipeline, revenue). +- Monitor pacing vs budget and highlight over/under-performing channels. +- Run root-cause analyses on creative, audience, and placement performance. +- Recommend reallocations, creative tests, and enablement actions. + +## Workflow +1. **Data Intake** – sync paid, owned, and earned channel data with unified taxonomy. +2. **Quality Checks** – validate UTMs, spend allocations, and attribution consistency. +3. **Performance Diagnostics** – compare to benchmarks, cohorts, and guardrails. +4. **Opportunity Identification** – surface quick wins, experiments, or rebalancing moves. +5. **Enablement & Follow-up** – brief channel owners, document actions, track results. + +## Outputs +- Channel scorecards with KPIs, benchmarks, and action items. +- Pacing alerts with recommended reallocations. +- Creative/test backlog prioritized by impact and urgency. + +--- diff --git a/agents/marketing-intelligence-lead.md b/agents/marketing-intelligence-lead.md new file mode 100644 index 0000000..4fed68c --- /dev/null +++ b/agents/marketing-intelligence-lead.md @@ -0,0 +1,29 @@ +--- +name: marketing-intelligence-lead +description: Owns cross-channel marketing analytics strategy, instrumentation, and + reporting cadences. +model: sonnet +--- + + +# Marketing Intelligence Lead Agent + +## Responsibilities +- Define KPI frameworks for awareness, demand, and lifecycle programs. +- Align marketing, RevOps, and finance on attribution, pacing, and investment guardrails. +- Maintain analytics roadmap, tooling, and governance documentation. +- Translate insights into exec-ready recommendations and enablement resources. + +## Workflow +1. **Metric Strategy** – map KPIs to funnel stages, personas, and investments. +2. **Instrumentation Review** – ensure UTMs, tracking plans, and dashboards stay healthy. +3. **Insight Sprints** – analyze performance trends, diagnose anomalies, and prioritize analyses. +4. **Narrative Delivery** – package insights for ELT, marketing leadership, and partner teams. +5. **Action Tracking** – log decisions, owners, and follow-up experiments or campaigns. + +## Outputs +- KPI blueprint with definitions, formulas, and guardrails. +- Executive summaries of marketing performance with actions/asks. +- Analytics backlog with prioritized projects and dependencies. + +--- diff --git a/commands/evaluate-attribution-models.md b/commands/evaluate-attribution-models.md new file mode 100644 index 0000000..8310995 --- /dev/null +++ b/commands/evaluate-attribution-models.md @@ -0,0 +1,34 @@ +--- +name: evaluate-attribution-models +description: Compares attribution models, highlights trade-offs, and recommends rollout plans. +usage: /marketing-analytics:evaluate-attribution-models --campaigns launch_q1,evergreen_abm --models first,last,position,data-driven --audience finance +--- + +# Command: evaluate-attribution-models + +## Inputs +- **campaigns** – list of campaigns/programs to analyze. +- **models** – attribution models to compare (first, last, linear, position, time-decay, data-driven). +- **audience** – finance | marketing-lead | ops | exec. +- **metrics** – choose KPIs (pipeline, revenue, CAC, payback, LTV, ROAS). +- **confidence** – optional minimum data confidence threshold to highlight gaps. + +## Workflow +1. **Data Preparation** – pull campaign performance, cost, and pipeline/revenue outcomes. +2. **Model Execution** – run requested models, normalize windows, and apply weighting rules. +3. **Sensitivity Analysis** – compare outcomes vs benchmarks, highlight variance drivers. +4. **Narrative Assembly** – contextualize trade-offs, governance considerations, and risks. +5. **Recommendation Engine** – propose primary model, fallback, and rollout/QA checklist. + +## Outputs +- Attribution comparison deck/table with KPI deltas per model. +- Recommendation memo with decision, rationale, and risk mitigations. +- Rollout plan including QA steps, owner assignments, and monitoring hooks. + +## Agent/Skill Invocations +- `attribution-architect` – leads methodology comparison. +- `marketing-intelligence-lead` – ensures narrative + stakeholder alignment. +- `attribution-playbook` skill – documents rules + templates. +- `exec-dashboard-blueprint` skill – packages executive summary. + +--- diff --git a/commands/monitor-channel-pacing.md b/commands/monitor-channel-pacing.md new file mode 100644 index 0000000..005ea26 --- /dev/null +++ b/commands/monitor-channel-pacing.md @@ -0,0 +1,34 @@ +--- +name: monitor-channel-pacing +description: Tracks spend, performance, and guardrails across paid and owned channels. +usage: /marketing-analytics:monitor-channel-pacing --window month --channels paid_search,linkedin,display --alerts true +--- + +# Command: monitor-channel-pacing + +## Inputs +- **window** – day | week | month | quarter | campaign. +- **channels** – comma-separated list (paid_search, paid_social, display, events, content, email). +- **budget** – optional target spend to compare pacing against. +- **alerts** – true/false to include guardrail breach alerts. +- **format** – dashboard | memo | slack. + +## Workflow +1. **Spend & Performance Sync** – pull channel spend, impressions, clicks, CPL, pipeline, revenue. +2. **Normalization** – convert currencies, align attribution windows, reconcile UTMs. +3. **Guardrail Checks** – compare to CAC, CPL, payback, or custom thresholds. +4. **Optimization Signals** – flag channels/assets needing creative refresh or budget shift. +5. **Packaging & Alerts** – publish dashboard/memo and optional Slack digest for owners. + +## Outputs +- Channel pacing dashboard with KPIs vs targets. +- Alert summary for guardrail breaches + recommended actions. +- Reallocation recommendations with projected impact. + +## Agent/Skill Invocations +- `channel-performance-analyst` – leads pacing diagnostics. +- `marketing-intelligence-lead` – confirms priorities + narratives. +- `channel-pacing-guardrails` skill – enforces budget/efficiency thresholds. +- `roi-benchmark-library` skill – supplies benchmarks for comparison. + +--- diff --git a/commands/produce-campaign-report.md b/commands/produce-campaign-report.md new file mode 100644 index 0000000..2dfc2b1 --- /dev/null +++ b/commands/produce-campaign-report.md @@ -0,0 +1,35 @@ +--- +name: produce-campaign-report +description: Generates cross-channel campaign performance report with insights and recommendations. +usage: /marketing-analytics:produce-campaign-report --campaign "Spring Launch" --window 30d --audience exec +--- + +# Command: produce-campaign-report + +## Inputs +- **campaign** – campaign/program identifier (matches MAP/CRM naming). +- **window** – analysis window (7d, 30d, campaign, custom). +- **audience** – exec | marketing-lead | channel-owner | async. +- **metrics** – optional override list for KPIs to highlight. +- **format** – deck | memo | dashboard | csv. + +## Workflow +1. **Data Assembly** – join paid, owned, and earned channel data with CRM pipeline/revenue fields. +2. **Attribution Layer** – apply default or requested model, annotate confidence and limitations. +3. **Performance Story** – highlight wins, underperformance, and causal insights. +4. **Action Plan** – recommend optimizations, tests, or budget shifts per channel/asset. +5. **Packaging** – tailor to audience with visuals, narrative, and calls-to-action. + +## Outputs +- Campaign performance package (deck/memo/dashboard) with KPIs, insights, and actions. +- Attribution summary with model notes and sensitivity ranges. +- Optimization plan with owners, due dates, and expected impact. + +## Agent/Skill Invocations +- `marketing-intelligence-lead` – frames narrative + executive summary. +- `channel-performance-analyst` – provides channel diagnostics and pacing alerts. +- `attribution-architect` – validates attribution logic and caveats. +- `attribution-playbook` skill – enforces methodology templates. +- `exec-dashboard-blueprint` skill – packages outputs for leadership reviews. + +--- diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..4b8b5a2 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,81 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:gtmagents/gtm-agents:plugins/marketing-analytics", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "5cdfa46c93f7864a0d6731ca9ac4fc67edeca55b", + "treeHash": "ec8185255150c1f177066a296bf639510dc9b1ff297670b7afac8d1f7d17ed98", + "generatedAt": "2025-11-28T10:17:15.031875Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "marketing-analytics", + "description": "Cross-channel marketing KPI frameworks, pacing guardrails, and attribution governance", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "00116295cc0c399a65fdefca44b6718d82c5d7d5222d6601a2db0d080f3a873e" + }, + { + "path": "agents/attribution-architect.md", + "sha256": "a59006a84a829e35662f7a254a206cab1042996db2ec229d64b51be5d13f3bda" + }, + { + "path": "agents/channel-performance-analyst.md", + "sha256": "ff1e7412a428948c74acf8f6749c0b295f9a1874c5ffad0f7ff3a107d783067a" + }, + { + "path": "agents/marketing-intelligence-lead.md", + "sha256": "9f5fb23b47eab7241c19c96fa75b0b071ed3d40c27a678e7ef385d4068bddd4f" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "8ce3c6e91bb29551fe25536d2bb3398e2472f8566be41666b7e34ce19acd2202" + }, + { + "path": "commands/monitor-channel-pacing.md", + "sha256": "0c64defebe02ac6a712eb43673319ddebd0df0a67baf89f1b7a7d51a513d47a1" + }, + { + "path": "commands/evaluate-attribution-models.md", + "sha256": "14dd2af1f86d79443fc1221719c18fa6abb8af21d511ba4ff221816cb01aa202" + }, + { + "path": "commands/produce-campaign-report.md", + "sha256": "e1f8e4096f680ca56746acc6d4e601e49684023913850326c46d68d7801dc63c" + }, + { + "path": "skills/exec-dashboard-blueprint/SKILL.md", + "sha256": "79f770cbd25c96a6d7f2a0baee1f2ca48d64fcd19a3439cc0e8b33ce689d8b78" + }, + { + "path": "skills/channel-pacing-guardrails/SKILL.md", + "sha256": "0d482353dacad31bcf6a1283e094ab3a9156df265775ceb796f2a8d3c532eb82" + }, + { + "path": "skills/roi-benchmark-library/SKILL.md", + "sha256": "61518e38a93fa2178aad5e7d787f2dcf542957802d62a52a7455a5027341ff7c" + }, + { + "path": "skills/attribution-playbook/SKILL.md", + "sha256": "4ce577c7318118219230b7b52659a1f36996b15d50f79105a1851a5a0009b8b9" + } + ], + "dirSha256": "ec8185255150c1f177066a296bf639510dc9b1ff297670b7afac8d1f7d17ed98" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/attribution-playbook/SKILL.md b/skills/attribution-playbook/SKILL.md new file mode 100644 index 0000000..a750563 --- /dev/null +++ b/skills/attribution-playbook/SKILL.md @@ -0,0 +1,31 @@ +--- +name: attribution-playbook +description: Standard operating guide for campaign tagging, attribution models, and + QA. +--- + +# Attribution Playbook Skill + +## When to Use +- Standing up or refreshing attribution models across teams. +- Training campaign owners on UTMs, tracking, and governance. +- Running QA before/after changing attribution weights or tooling. + +## Framework +1. **Taxonomy Rules** – channel, campaign, creative, and experiment naming standards. +2. **Model Catalog** – when to use first/last/linear/position/data-driven with pros/cons. +3. **Data Contracts** – required fields, systems of record, sync cadence. +4. **QA Checklist** – sample records, dedupe logic, cross-tool reconciliation. +5. **Change Management** – approval workflow, communications, and measurement of impact. + +## Templates +- UTM builder + validation sheet. +- Attribution model comparison matrix. +- QA runbook for campaign launches and quarterly audits. + +## Tips +- Keep a shared "gotchas" log for recurring tagging errors. +- Align with finance on ROI/CAC definitions before rolling out model changes. +- Pair with `evaluate-attribution-models` for decision-ready narratives. + +--- diff --git a/skills/channel-pacing-guardrails/SKILL.md b/skills/channel-pacing-guardrails/SKILL.md new file mode 100644 index 0000000..d581c17 --- /dev/null +++ b/skills/channel-pacing-guardrails/SKILL.md @@ -0,0 +1,31 @@ +--- +name: channel-pacing-guardrails +description: Guardrail framework for monitoring spend, efficiency, and CAC thresholds + by channel. +--- + +# Channel Pacing Guardrails Skill + +## When to Use +- Reviewing weekly/monthly pacing to stay within spend and efficiency targets. +- Triggering alerts when CPL/CAC/ROAS drift beyond tolerance. +- Aligning finance + marketing on reallocation decisions. + +## Framework +1. **Budget Bands** – define min/max pacing per channel, region, and campaign tier. +2. **Efficiency Guardrails** – set CAC, CPL, ROAS, payback thresholds with warning/critical bands. +3. **Alert Workflow** – specify channels, owners, escalation paths, and notification cadence. +4. **Exception Policy** – document when overrides are allowed and approval requirements. +5. **Post-Mortem Loop** – capture breaches, actions taken, and guardrail adjustments. + +## Templates +- Guardrail matrix (channel x metric x threshold). +- Alert playbook with messaging, owner, and resolution steps. +- Reallocation recommendation sheet linking to finance approvals. + +## Tips +- Sync guardrail metrics with `roi-benchmark-library` to keep thresholds grounded in data. +- Tie alerts to `/marketing-analytics:monitor-channel-pacing` outputs for automation. +- Include leading indicators (CTR, CPC) to catch issues before CAC blows up. + +--- diff --git a/skills/exec-dashboard-blueprint/SKILL.md b/skills/exec-dashboard-blueprint/SKILL.md new file mode 100644 index 0000000..1aa7697 --- /dev/null +++ b/skills/exec-dashboard-blueprint/SKILL.md @@ -0,0 +1,63 @@ +--- +name: exec-dashboard-blueprint +description: Layout and storytelling guide for marketing analytics executive dashboards. +--- + +# Executive Dashboard Blueprint Skill + +## When to Use +- Preparing ELT/board-ready snapshots of marketing performance. +- Standardizing dashboard layout across BI, RevOps, and marketing teams. +- Packaging insights from `/marketing-analytics` commands into clear narratives. + +## Framework +1. **Story Arc** – headline → KPI spine → risks/opps → actions. +2. **KPI Tiles** – awareness, demand, pipeline, revenue, efficiency metrics with traffic lights. +3. **Drill Cards** – channel, campaign, and audience breakouts linking to deeper views. +4. **Insight Callouts** – annotate anomalies, root causes, and required decisions. +5. **Action Register** – owners, due dates, and follow-ups surfaced alongside metrics. + +## Templates +- 3-slide deck structure (headline, KPIs, actions). +- Dashboard wireframe with recommended chart types + layout. +- Annotation checklist ensuring context + next steps accompany data. +- **GTM Agents KPI Guardrail Sheet** – baseline vs target vs alert ranges for reach, pipeline, win rate, CAC payback @puerto/README.md#214-241. +- **Measurement Spec** – metric definitions, filters, refresh cadence, owner column. +- **Weekly Exec Packet** – combines dashboard screenshots, narrative summary, decision log (mirrors GTM Agents Data Analyst deliverable). + +## Tips +- Limit each dashboard view to one primary objective to avoid overload. +- Embed links back to commands (`produce-campaign-report`, `monitor-channel-pacing`) for drilldowns. +- Archive monthly snapshots for trend storytelling. +- Adopt GTM Agents cadence: Monday data QA, Tuesday ELT preview, Thursday exec meeting, Friday retro + action register updates. +- Highlight which KPIs are within guardrail, trending to alert, or breaching (RAG) so leadership can react quickly. +- Pair with `docs/gtm-essentials.md` tools: Context7 for latest GA4 docs, Serena for patching data models, Sequential Thinking for retro facilitation. + +## GTM Agents Dashboard Governance Overlay +1. **Data QA Loop** – run freshness + anomaly checks before distributing (log results in audit trail). +2. **Narrative Structure** – use Story Arc to link KPI shifts to drivers and required decisions. +3. **Action Register** – every dashboard delivery must include owner, due date, and status for prescribed actions. +4. **Escalation** – if guardrail breach persists >2 weeks, escalate to Chief Product Officer / Sales Director per GTM Agents governance. + +## KPI Guardrails (GTM Agents Reference) +- Awareness (reach/impressions) ±8% window before alerting; >12% triggers campaign review. +- Pipeline add ≥3x quota per quarter; warn at 2.5x. +- Win rate ≥25% for in-quarter commit; escalate if <20%. +- CAC payback ≤14 months; escalate if >16 months. + +## Weekly Exec Packet Outline +``` +1. Headline + KPI spine (traffic lights per guardrail) +2. Insights & Drivers – 3 bullets tying KPI movement to channels/programs +3. Required Decisions – what leadership must approve/block +4. Action Register – owner, due date, status +5. Appendix – detailed drill cards + methodology +``` + +## Tool Hooks +- **Context7** – fetch current platform docs (GA4, Salesforce) referenced in measurement specs. +- **Serena** – update BI repo SQL notebooks or dbt models safely. +- **Sequential Thinking** – facilitate monthly retros and architecture of dashboard iterations. +- **Playwright** – capture dashboard screenshots or verify embedded web components before distribution. + +--- diff --git a/skills/roi-benchmark-library/SKILL.md b/skills/roi-benchmark-library/SKILL.md new file mode 100644 index 0000000..e12ef78 --- /dev/null +++ b/skills/roi-benchmark-library/SKILL.md @@ -0,0 +1,31 @@ +--- +name: roi-benchmark-library +description: Reference benchmarks for CAC, CPL, ROAS, and payback across channels + and segments. +--- + +# ROI Benchmark Library Skill + +## When to Use +- Comparing current performance vs historical or industry benchmarks. +- Setting guardrails for budgeting, pacing, and campaign approvals. +- Equipping finance/marketing leaders with realistic ROI expectations. + +## Framework +1. **Benchmark Sources** – internal history, partner data, analyst reports, industry surveys. +2. **Segmentation** – channel, region, persona, product, funnel stage. +3. **Metric Definitions** – CAC, CPL, ROAS, payback, pipeline-to-spend, revenue-to-spend. +4. **Update Cadence** – monthly for active channels, quarterly for strategic benchmarks. +5. **Usage Guidance** – when to escalate variances, how to contextualize outliers. + +## Templates +- Benchmark matrix (channel x metric x segment). +- Variance alert sheet with thresholds + recommended actions. +- Executive summary page for QBRs. + +## Tips +- Normalize for currency changes and attribution windows before comparing. +- Pair with `monitor-channel-pacing` to trigger alerts against guardrails. +- Share benchmark deltas with channel owners to inform creative/test roadmaps. + +---