Audience segmentation brief

Audience Segmentation Brief

Convert available customer and market data into actionable audience segments for media, CRM, creative, measurement, and business decisions. Treat segmentation as logistics classification: every audience has a destination, route, message, value potential, and activation method.

How This Skill Orchestrates

1. Web search (Claude — MANDATORY): Search Kantar Worldpanel for category penetration/frequency, industry CLV benchmarks, platform audience sizes by country
2. Script execution (scripts/segmentation_engine.py): RFM scoring + CLV estimation (BG/NBD + Gamma-Gamma heuristic) + K-Means clustering + Consumer Identity Graph resolution. Runs multiple methods based on data availability
3. Reference lookup (references/segmentation_methodology.md): RFM framework (11 segments), PyMC-Marketing CLV methodology, K-Means guide, Identity Graph architecture (7 match key types), 1st/2nd/3rd party data strategy, LATAM/Mexico specifics (LFPDPPP, WhatsApp addressability, phone-first matching)
4. Upstream context (Claude): Pull channel allocation from media-routing-planner, scope from scope-audit, CRM platform from crm-journey-architect
5. Visual output (Visualizer): Segment distribution chart + CLV tier pyramid + Identity Graph match rate + activation matrix

Models used (all justified):

Model	When to use	Stack layer
RFM	Transaction data available (always start here)	Measurement — clustering
CLV (BG/NBD + Gamma-Gamma)	Value-based segmentation needed; script uses heuristic, production uses PyMC-Marketing	Measurement — CLV
K-Means	Behavioral data (events, clicks, content) beyond transactions	Measurement — clustering
Identity Graph	Multi-source data (CRM + app + website + 2P/3P)	Interpretation — entity resolution
Proxy segmentation	No data available — infer from demographics/geo	Interpretation — LLM inference

For full Bayesian CLV, the reference provides PyMC-Marketing code (BetaGeoModel + GammaGammaModel). The script's built-in CLV is a heuristic approximation — use PyMC for production.

Quick Reference

Resource	Purpose	Usage
scripts/segmentation_engine.py	RFM scorer (11 segments), CLV estimator (5 tiers), K-Means (configurable K), Identity Graph builder (deterministic multi-key matching), proxy segmentation fallback	python segmentation_engine.py --input config.json --output segments.json
scripts/segment_overlap_checker.py	Detects overlapping segments using Jaccard similarity. Flags critical/high/medium overlaps with consolidation recommendations	python segment_overlap_checker.py --input segments.json --output overlaps.json
scripts/addressability_checker.py	Validates what % of each segment is addressable per channel (email/SMS/WhatsApp/push/paid), considering consent status and data availability	python addressability_checker.py --segments segs.json --contacts contacts.json
references/segmentation_methodology.md	RFM framework + scoring table, CLV methodology (BG/NBD + GG with PyMC code), K-Means feature guide, Identity Graph architecture (match key hierarchy, confidence scoring), 1P/2P/3P data strategy by maturity level, activation patterns by segment, LATAM specifics	Read for methodology and activation patterns
references/consent_and_addressability.md	Consent status logic (6 states), regulatory framework (LFPDPPP Mexico, GDPR, CCPA, LGPD Brazil), addressability rates by channel and country (LATAM-specific), cross-channel consent matrix	Read for compliance and activation feasibility
references/suppression_guidelines.md	11 suppression types with duration rules, suppression logic by segment, platform-specific suppression (SFMC/AJO/paid), re-entry cooldown rules, frequency caps by channel, deliverability protection thresholds	Read for suppression strategy and list hygiene

How to Use the Script

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

config = {
    "client_name": "AcmeAuto MX",
    "objective": "Identify high-value customers for loyalty program + lookalike seeding",
    "methods": ["rfm", "clv", "identity_graph"],
    "clv_months": 12,
    "transactions": [
        {"customer_id": "C001", "date": "2026-01-15", "amount": 850},
        {"customer_id": "C001", "date": "2026-03-20", "amount": 120},
        {"customer_id": "C002", "date": "2025-11-10", "amount": 45000},
        # ... more transactions
    ],
    "data_sources": [
        {"source_name": "Salesforce CRM", "source_type": "1p",
         "records": [{"id": "C001", "email": "[email protected]", "phone": "+525512345678", "crm_id": "SF-001"}]},
        {"source_name": "Website CDP", "source_type": "1p",
         "records": [{"id": "W001", "email": "[email protected]", "device_id": "abc123"}]},
        {"source_name": "Retail partner", "source_type": "2p",
         "records": [{"id": "R001", "phone": "+525512345678", "crm_id": ""}]},
    ],
}

engine = SegmentationEngine(config)
result = engine.segment()
# result.segments, result.rfm_distribution, result.clv_tiers, result.identity_graph

Process

Step 1 — Define the Business Decision

What decision does this segmentation support? "Who to target for loyalty" ≠ "Who to exclude from prospecting" ≠ "Who to winback."

Step 2 — Identify Available Data

Inventory all data sources: CRM (1P), website/app (1P), transactions (1P), retail partner (2P), DMP/DSP (3P). Note consent status per source.

Step 3 — Build Identity Graph (if multi-source)

When data comes from multiple sources, resolve identities first. Run the Identity Graph builder to match records across sources using email → CRM ID → phone → device ID hierarchy. This creates a unified audience foundation.

Step 4 — Run RFM Segmentation (if transactions available)

Score customers on Recency, Frequency, Monetary. Produces 11 actionable segments from "Champions" to "Lost." This is the foundation — always run RFM if transaction data exists.

Step 5 — Estimate CLV (if value-based segmentation needed)

Layer CLV on top of RFM to identify not just who's active, but who's most valuable over time. Uses BG/NBD + Gamma-Gamma methodology. For production, use PyMC-Marketing (see reference).

Step 6 — Run K-Means (if behavioral data available)

When you have non-transactional behavioral data (page views, app events, content consumption), use K-Means to discover natural behavioral clusters.

Step 7 — Define Activation Method per Segment

Map each segment to its activation channel: CRM journey, paid media audience, lookalike seed, retargeting list, suppression list, sales handoff.

Step 8 — Define Suppression Logic

Champions → suppress from prospecting (waste). Lost → suppress from CRM after final winback attempt. High-CLV → suppress from discount campaigns (protect margin).

Step 9 — Define Measurement per Segment

Track CVR and LTV per segment separately. Run incrementality tests on high-value segments. Use holdout groups for CRM journeys.

Output Format

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

Visual Dashboard (Primary)

Render as inline HTML widget:

• Header with client, objective, methods used, total customers
• RFM segment distribution — horizontal stacked bar showing segment sizes, color-coded by priority (Champions = green, Lost = gray)
• CLV tier pyramid — if CLV was run, show 5-tier pyramid with count and avg CLV per tier
• Identity Graph metrics — if graph was built, show: total identities, match rate %, sources matched, confidence distribution
• Activation matrix — table mapping each segment to media use, CRM use, creative implication
• Data gaps — flagged items
• sendPrompt() buttons: "Design CRM journey for [segment]" → crm-journey-architect, "Build media plan targeting [segments]" → media-routing-planner

Markdown Brief (Secondary)

## 👥 AUDIENCE SEGMENTATION BRIEF — [Client]

### Segmentation objective
[Business decision this supports]

### Methods used
[RFM + CLV + K-Means + Identity Graph — which were run and why]

### Identity graph summary
| Metric | Value |
[Total records, identities, match rate, sources, confidence]

### Data sources
| Source | Type (1P/2P/3P) | Fields | Reliability |

### Segments
| Segment | Method | Size | Avg value | CLV tier | Priority | Activation |
[One row per segment, ranked by priority]

### CLV tier distribution
| Tier | Count | Avg CLV | Action |

### Activation brief
| Segment | Media use | CRM use | Creative | Measurement |

### Suppression logic
[Which segments to exclude from which channels and why]

### Data gaps
[Missing fields, consent issues, addressability limits]

### Recommendation
[What to activate first, what to test, what data to collect next]

Examples

Example 1 — E-commerce RFM + CLV: User provides 6 months of transaction data for an e-commerce client in Mexico. → RFM produces 8 segments (Champions 12%, At Risk 18%, Lost 22%). CLV shows Platinum tier (top 20%) = 65% of revenue. Activation: Champions → lookalike seed + loyalty. At Risk → winback journey (SFMC). Lost → suppress from paid.

Example 2 — Identity Graph + segmentation: User provides CRM data + website CDP + retail partner data. → Identity Graph merges 45K records into 28K identities (62% cross-source match). RFM on unified data produces cleaner segments. Phone-based matching drives 70% of matches (Mexico market — phone > email for matching).

Example 3 — No data (proxy): User: "We're launching a new product for 25-35 women in Mexico City interested in skincare." → Proxy segmentation: High intent (skincare search behavior), Category buyers (beauty e-commerce), Broad awareness (25-35F metro). Data gap flagged — recommend pixel installation + CRM collection to enable RFM within 90 days.

Skill Chaining

Direction	Skill	Connection
Upstream	scope-audit	Validates segmentation work is in SOW
Upstream	media-routing-planner	Defines which audiences need activating
Downstream	crm-journey-architect	Segment definitions → journey entry criteria
Downstream	media-routing-planner	Audience sizes → budget allocation per segment
Downstream	creative-supply-planner	Segment count → creative variant needs
Downstream	measurement-incrementality	Segments → holdout/test group design
Downstream	executive-growth-memo	Segment insights → leadership narrative