Ppa continuous optimization

ppa-continuous-optimization

Closes the PPA loop: monitors KPIs by SKU × channel × zone × segment, fires CUSUM early-warning alerts, applies auto-pricing business rules, and triggers ppa-design-optimizer for full redesign when structural shifts are detected. TomTom MCP is core — every alert is geo-located and prioritized by zone.

---

The Continuous Optimization Loop

DESIGN (ppa-design-optimizer)
        ↓ launch
MONITOR (channel_kpis.py + early_warning_system.py)
    ├── Minor deviation → auto_pricing_rules.py → tactical adjustment
    ├── Major deviation → trigger ppa-design-optimizer → architecture update
    └── Geographic deviation → TomTom zone map → zone-specific intervention
        ↓ 4-week cycle
REPORT (optimization_dashboard.py + alert_logger.py)
        ↓
REDESIGN (when structural shift detected: new competitor, channel reset, inflation)

Key insight: PPA is not a one-time exercise. It decays within 8–16 weeks as competitors respond, inflation erodes price tiers, and shopper behavior shifts. The continuous loop converts PPA from a project into an operating system.

---

Core Equations

KPI tracking

# Market share by volume:
share_vol_i = vol_i / Σ_j vol_j  (across competitive set)

# Relative price index:
RPI_i = price_i / weighted_avg_competitor_price

# Velocity (sell-out per point of distribution):
velocity_i = vol_i / distribution_numeric_i

# SKU profitability index:
profit_idx_i = (price_i - cost_i) × velocity_i / category_avg_profitability

CUSUM early warning

# Standard CUSUM on weekly KPI residuals:
S_t = max(0, S_{t-1} + (x_t - μ₀ - k))
Alert when: S_t > h  (h = 4σ decision interval)

# Shewhart control chart (faster for large shifts):
Alert when: |x_t - μ₀| > 3σ  (3-sigma rule)

# Combined: CUSUM for gradual drift, Shewhart for sudden shocks

Auto-pricing rules engine

# Rule structure:
IF  KPI_delta(metric, sku, channel, zone) < threshold
AND consecutive_periods >= n_periods
AND NOT already_adjusted_in_last(cooldown_weeks)
THEN  apply_action(action_type, magnitude, sku, channel, zone)

# Actions available:
# "price_down_pct": reduce shelf price by X%
# "promo_activate": trigger trade promotion
# "channel_delist": flag for channel removal
# "escalate_redesign": trigger ppa-design-optimizer

Zone priority scoring (TomTom-enhanced)

# Zone priority for intervention:
zone_priority = (alert_severity × channel_density) / distance_to_support

# TomTom inputs:
# - n_POIs by channel type per zone (tomtom-fuzzy-search)
# - Zone-level sell-out from client data
# - Competitor POI density (proxy for competitive pressure)

---

Workflow

Step 1 — Data input

# data-intake-normalizer: date, sku, channel, zone, volume, price,
#                         market_share, distribution_numeric
# From MCP: Supermetrics (digital), Adspirer (media), client ERP (sell-out)

Step 2 — KPI computation

python scripts/channel_kpis.py \
    --data /mnt/user-data/uploads/ppa_performance.xlsx \
    --competitive-set /mnt/user-data/uploads/competitors.xlsx \
    --output results/kpis.json

Step 3 — Early warning system

python scripts/early_warning_system.py \
    --kpis results/kpis.json \
    --thresholds '{"market_share":-0.10,"velocity":-0.15,"rpi":0.12}' \
    --n-periods 2 \
    --output results/alerts.json

Step 4 — Auto-pricing rules

python scripts/auto_pricing_rules.py \
    --alerts results/alerts.json \
    --rules /mnt/user-data/uploads/pricing_rules.json \
    --output results/actions.json

Step 5 — TomTom geo-intelligence (ALWAYS)

→ tomtom-fuzzy-search: supermarkets + convenience stores per zone
→ Cross: sell-out velocity per zone × POI density per zone
→ Compute zone_priority score
→ tomtom-dynamic-map: choropleth of alert severity by zone
  + markers for top-priority intervention points
→ If zone shows structural shift (competitive entry) → flag for redesign

Step 6 — Dashboard + alert log

python scripts/optimization_dashboard.py \
    --kpis results/kpis.json \
    --alerts results/alerts.json \
    --actions results/actions.json \
    --output dashboard_data.json

python scripts/alert_logger.py \
    --alerts results/alerts.json \
    --actions results/actions.json \
    --output results/alert_log.json

Step 7 — Redesign trigger (if structural shift)

IF structural_shift_detected:
  → sendPrompt("RUN ppa-design-optimizer with updated competitive landscape")
  → Full architecture redesign cycle

Output sequence:

1. [bash_tool] channel_kpis.py → early_warning_system.py → auto_pricing_rules.py
2. [TomTom MCP] ALWAYS — zone KPI map + POI density + priority zones
3. [web_search] "competitive price changes [category] [market] last 4 weeks"
4. [show_widget] Complete inline dashboard — traffic-light scorecards + zone map
5. [text] NBA by zone/channel/SKU/segment
6. [text] Escalation recommendation if structural shift

---

Dashboard Panels (all visible inline)

1. KPI bar — overall portfolio health score, active alerts count, zones in red, avg RPI drift, SKUs below velocity threshold, auto-actions taken
2. Traffic-light SKU scorecard — red/yellow/green per SKU × channel
3. Alert timeline — waterfall of alerts this cycle with severity + auto-action
4. Zone performance map — TomTom choropleth: green/yellow/red zones by KPI
   • POI markers for priority intervention locations
5. Auto-pricing action log — rules triggered, magnitude, expected impact
6. Trend panel — 12-week rolling KPIs by SKU (market share + velocity + RPI)
7. Redesign trigger meter — distance from structural-shift threshold

---

Optimization Cycle Cadence

Frequency	Activity	Trigger
Weekly	KPI pull + CUSUM check + zone map refresh	Automated (batch/MCP)
Bi-weekly	Auto-pricing rules execution	Alert level ≥ MEDIUM
Monthly	Full PPA performance review	Standing calendar
Quarterly	Architecture redesign assessment	Structural shift or QBR
Ad-hoc	Emergency redesign	Alert level = CRITICAL

---

Marketer Insights Layer (MANDATORY)

Search before benchmarking

web_search: "PPA continuous optimization FMCG real-time pricing [year]"
web_search: "price monitoring competitive intelligence [category] [market] [year]"
web_search: "dynamic pricing consumer goods LATAM [year]"

Translate to business language

Technical	Business meaning
CUSUM alert S_t=6.2 (h=4)	"Market share has been drifting down for 3 weeks — not random noise"
zone_priority = 0.91	"Zone Cuauhtémoc needs immediate intervention — high traffic, red KPIs"
RPI drift = +0.14	"We are now 14% more expensive than competitors — above the 10% threshold"
velocity_delta = -18%	"This SKU sells 18% fewer units per store per week vs 4 weeks ago"
structural_shift = TRUE	"The pattern cannot be fixed with a price tweak — full redesign needed"

NBA

• Zone-first prioritization: "Focus on Zone [X] first — highest POI density + worst KPIs = maximum impact"
• Tactical adjustment: "Auto-rule fired: reduce [SKU] price 3% in TT for 4 weeks — expected +[N]% velocity"
• Competitive alert: "RPI crossed 10% threshold — competitor may have launched promo. Activate cross-check"
• Velocity floor: "[SKU] below minimum velocity threshold for [N] weeks → flag for channel delist or promo activation"
• Redesign signal: "4 of 6 KPIs in RED for 3+ consecutive periods — trigger ppa-design-optimizer full cycle"
• Geographic insight: "Zone TT-dense (Tepito, Neza) shows -22% velocity — entry SKU price may need zone-specific adjustment"

---

Redesign Trigger Conditions

Escalate from tactical adjustment to full ppa-design-optimizer redesign when:

TRIGGER redesign IF ANY:
  - market_share_drop > 15% sustained 4+ weeks
  - new_competitor_entry detected in TomTom POI data
  - category_inflation > 8% cumulative (thresholds have shifted)
  - channel_restructuring (major retailer policy change)
  - n_red_alerts >= 4 simultaneously
  - structural_break detected in CUSUM (F-stat > critical value)

---

Integration with OS

Skill	Direction	Purpose
ppa-design-optimizer	→ calls when redesign triggered	Full architecture update
price-threshold-detection	pulls thresholds	Validates if RPI crossed danger zone
price-elasticity-modeling	pulls elasticity	Updates auto-pricing magnitude
ppa-financial-model	cross-checks P&L	Validates auto-action won't destroy margin
trade-promotion-roi	activation layer	Converts alert into promo plan
weekly-control-tower	receives alerts	Feeds OS-wide monitoring cycle
executive-growth-memo	receives summary	C-level escalation when critical
measurement-incrementality	validates auto-actions	Did the auto-pricing actually work?

---

References

• references/cusum_ppa_calibration.md — CUSUM parameters for PPA KPIs
• references/auto_pricing_rule_library.md — Predefined business rules
• references/zone_scoring_model.md — TomTom POI density → zone priority
• references/redesign_trigger_framework.md — When to escalate vs adjust