---
name: ppa-pack-size-leverage
description: >
  Evaluates and recommends pack size changes (shrinkflation, upsizing, downscaling)
  based on elasticity and margin. Trigger when asked to: optimize cash margin via
  pack size, evaluate shrinkflation risk, decide between reducing or increasing pack
  size, model upsizing impact, simulate pack-price combinations, or find optimal pack
  size. Also trigger for: "shrinkflation", "upsizing", "downscaling", "margen en
  efectivo", "cash margin", "cambio de gramaje", "reducir pack", "aumentar tamaño",
  "leverage de pack", "optimizar margen sin subir precio". TomTom MCP activates when
  zone/city data present. Always renders complete inline HTML dashboard with decision
  tree, scenario simulator, and NBA by market, category, channel, and SKU.
---

# ppa-pack-size-leverage

Evaluates shrinkflation, upsizing, and downscaling strategies using elasticity-adjusted
cash margin simulation. Implements EY PPA decision tree (p.5) and cash margin opportunity
formula (p.6). Always outputs complete inline dashboard.

---

## Plain Language

```
"¿Debo reducir el pack de 500g a 450g?"     → shrinkflation_calculator.py
"¿Qué pasa si aumento a 600g al mismo precio?" → upsizing_evaluator.py
"¿Cuál es la mejor estrategia para este SKU?"  → pack_size_decision_tree.py
"Simula 6 escenarios de tamaño × precio"       → scenario_simulator.py
"¿Cuál es el tamaño óptimo que max el margen?" → cash_margin_optimizer.py
```

**Core insight (EY PPA p.5-6):**
Maximizing unit margin is the wrong objective. The right objective is **cash margin**
(volume × unit margin). Upsizing at constant price sacrifices unit margin but can
massively increase cash margin if elasticity is high enough. Shrinkflation does the
opposite — preserves unit margin but risks cash margin if consumers notice.

---

## Core Equations (EY PPA p.6)

### Cash margin formula
```python
# Unit margin:
margin_per_unit = price - (cost_per_g × pack_size_g)

# Cash margin (what the business actually earns):
cash_margin = volume × margin_per_unit

# Delta cash margin from pack size change:
delta_cash_margin = (volume_new × margin_new) - (volume_old × margin_old)
```

### Shrinkflation impact
```python
# Implicit price increase from pack reduction:
pct_implicit = (size_old - size_new) / size_new   # eq. per gram basis

# Adjusted volume (demand response to implicit price change):
volume_new = volume_old × (1 + elasticity × pct_implicit)

# New unit margin (same shelf price, lower cost):
cost_new = cost_per_g × size_new
margin_new = price - cost_new

# Cash margin impact:
delta_cash = (volume_new × margin_new) - (volume_old × margin_old)
```

### Upsizing impact
```python
# Upsizing: increase pack size at SAME price
# Implicit price decrease per gram:
pct_implicit = (size_new - size_old) / size_old   # negative effect on margin

# Volume lift (demand responds to lower effective price):
volume_new = volume_old × (1 + abs(elasticity) × pct_implicit)

# New unit margin (same price, higher cost):
cost_new = cost_per_g × size_new
margin_new = price - cost_new

# Cash margin — volume lifts but margin per unit falls:
delta_cash = (volume_new × margin_new) - (volume_old × margin_old)
```

### Optimal pack size (cash margin maximization)
```python
# Optimize over pack size s:
max_s  cash_margin(s) = volume(s) × (price - cost_per_g × s)
where: volume(s) = volume_base × (s / size_base) ^ |elasticity|

# FOC: d(cash_margin)/ds = 0
# Analytical solution: s_opt = price / (2 × cost_per_g)
# when elasticity = -1 (unit elastic)
# General: use numerical optimizer
```

---

## EY Decision Tree (p.5)

```
                    ┌─────────────────┐
                    │ Analyze margin  │
                    │ + elasticity    │
                    └────────┬────────┘
              ┌──────────────┴──────────────┐
         Low margin                    High margin
              │                             │
    ┌─────────┴─────────┐       ┌──────────┴──────────┐
 Low elasticity  High elasticity  Low elasticity  High elasticity
    │                 │             │                  │
 SHRINKFLATION   DOWNSCALING    HOLD / MONITOR     UPSIZING
 (reduce pack,   (reduce pack   (neither hurts     (increase pack,
  keep price)    AND price)      significantly)     keep price)
```

Additional trigger conditions:
- Price crossing threshold → Upsizing (avoid crossing, maintain price)
- Price too high vs category → Downscaling (reduce both)
- Consumer trust risk → prefer Upsizing over Shrinkflation

---

## Workflow

### Step 1 — Data input
```bash
# data-intake-normalizer first
# Required: price, pack_size_g, cost_per_g, volume, elasticity
# Optional: region, channel, segment, threshold_price
```

### Step 2 — Decision tree classification
```bash
python scripts/pack_size_decision_tree.py \
    --price 18.50 --size-g 500 --cost-per-g 0.018 \
    --volume 1000 --elasticity -1.42 \
    --margin-threshold 0.25 --threshold-price 19.90 \
    --output results/decision.json
```

### Step 3 — Run recommended strategy script
```bash
# If shrinkflation recommended:
python scripts/shrinkflation_calculator.py \
    --price 18.50 --size-old 500 --size-new 450 \
    --cost-per-g 0.018 --volume 1000 --elasticity -1.42 \
    --output results/shrinkflation.json

# If upsizing recommended:
python scripts/upsizing_evaluator.py \
    --price 18.50 --size-old 500 --size-new 600 \
    --cost-per-g 0.018 --volume 1000 --elasticity -1.42 \
    --output results/upsizing.json
```

### Step 4 — Scenario simulation
```bash
python scripts/scenario_simulator.py \
    --price 18.50 --size-base 500 --cost-per-g 0.018 \
    --volume 1000 --elasticity -1.42 \
    --sizes "400,450,500,550,600,650" \
    --price-changes "-10,-5,0,5,10" \
    --output results/scenarios.json
```

### Step 5 — Cash margin optimization
```bash
python scripts/cash_margin_optimizer.py \
    --price 18.50 --size-base 500 --cost-per-g 0.018 \
    --volume 1000 --elasticity -1.42 \
    --size-range "300,700" \
    --output results/optimum.json
```

### Step 6 — Geographic variation (TomTom)
```
When zone/city data present:
→ tomtom-fuzzy-search: channel POI density per zone
→ Run scenario_simulator per zone cluster
→ Different elasticity by zone → different optimal pack per zone
→ tomtom-dynamic-map: recommended strategy by zone (choropleth)
```

**Output sequence:**
```
1. [bash_tool] Decision tree → identify strategy
2. [bash_tool] Relevant scripts + scenario_simulator
3. [web_search] "pack size strategy [category] [market] [year]" +
                "shrinkflation consumer reaction CPG LATAM [year]"
4. [TomTom MCP] If geographic data present
5. [show_widget] Complete inline dashboard
6. [text] NBA + market/category/SKU context
7. [text] Caveats
```

---

## Dashboard Panels (all visible inline)

1. **KPI bar** — recommended strategy, delta cash margin ($), current margin %,
   optimal pack size (g), shrinkflation volume risk, upsizing cash margin lift
2. **Decision tree panel** — visual tree with current SKU position highlighted
3. **Cash margin waterfall** — base vs shrinkflation vs upsizing vs optimum
4. **Scenario heatmap** — size × price combination cash margin matrix
5. **Shrinkflation vs upsizing comparison** — side-by-side metrics table
6. **Cash margin optimization curve** — cash margin vs pack size (parabola)
7. **Geographic strategy map** — TomTom choropleth when zone data present

---

## Marketer Insights Layer (MANDATORY)

### Search before benchmarking
```
web_search: "shrinkflation consumer awareness [category] [market] [year]"
web_search: "pack size strategy CPG margin optimization [year]"
web_search: "upsizing vs shrinkflation FMCG [category] LATAM [year]"
```

### Translate to business language

| Technical | Business meaning |
|---|---|
| delta_cash = +$8,400/month | "Upsizing adds $8,400/mo in cash — even though unit margin drops 15%" |
| pct_implicit = 11.1% | "Consumers experience an 11% effective price increase from 500→450g" |
| E × pct_implicit = -15.8% | "Shrinkflation costs 15.8% volume — partially offset by margin recovery" |
| s_opt = 480g | "480g maximizes cash margin — not your current 500g, not 450g" |
| margin_pct falls from 42% to 35% | "Unit margin shrinks but you sell 28% more volume — net gain" |

### NBA
- **Strategy call:** "Decision tree → [STRATEGY] for this SKU. Rationale: [margin × elasticity logic]"
- **Pack ceiling:** "Do not shrink below [Xg] — beyond that, volume loss exceeds margin gain"
- **Upsizing ROI:** "Going 500g→600g at $18.50 adds [N] units/mo and $[M] cash margin/mo"
- **Timing:** "Execute pack change at promo window — shopper disruption is lower during promotion periods"
- **Communication:** "If shrinkflating: do NOT communicate the change proactively — brand risk.
  If upsizing: communicate loudly — 'More for the same price' is a brand equity deposit"
- **Zone differentiation:** "Zone [A] (MT-heavy, low elasticity) → shrinkflation safe.
  Zone [B] (TT-heavy, high elasticity) → avoid shrinkflation, prefer upsizing"

---

## Key Caveats

- **Consumer detection lag:** Shrinkflation impact on volume may take 4–12 weeks to
  manifest as consumers deplete existing stock before noticing change
- **Retailer relationship:** Large pack changes require retailer notification —
  planogram reset costs can partially offset margin gains
- **Legal / labeling:** Pack size changes require updated nutritional labeling
  (Mexico: NOM-051) — budget 6–8 weeks for compliance
- **Elasticity asymmetry:** Upsizing uses the same elasticity coefficient as a
  price cut, but behavioral response may differ — consumers respond more to
  perceived gains (upsizing) than losses (price cuts)
- **Cost assumption:** Model assumes linear cost-per-gram — validate with procurement
  if pack change alters packaging format significantly

---

## Integration with OS

| Skill | Handoff |
|---|---|
| `data-intake-normalizer` | Validate price/size/cost/volume/elasticity input |
| `price-threshold-detection` | Threshold price feeds decision tree trigger |
| `price-elasticity-modeling` | Elasticity β feeds all impact calculations |
| `ppa-value-perception` | WTP and perception failure validate shrink risk |
| `ppa-assortment-diagnosis` | Optimal pack size feeds white space analysis |
| `trade-promotion-roi` | Pack change timing aligns with promo calendar |
| `margin-simulation` | Cash margin delta feeds P&L model |