# Agent prompt: diagnose and repair a custom PyMC-Marketing 1.x MMM with a prior sweep

Use this prompt with Codex, Claude or Cursor from the root of this repository.

```text
You are working on a PyMC-Marketing 1.x MMM.

Read README.md, BLOG.md, AGENTS.md and
pymc-marketing-sweep/.agents/skills/pymc-marketing-sweep/SKILL.md first.
Do not modify the sweep statistical engine unless a failing test demonstrates a bug.

Goal
====
Diagnose a difficult hierarchical MMM, obtain a trustworthy reference posterior,
screen plausible prior changes with PSIS, then validate the least-invasive safe
candidate with one real NUTS refit.

Start with the data
===================
Before changing priors, inspect the modelling data and explain:
- the panel dimensions and number of cells
- time coverage
- missingness or sparse cells
- scale differences across brands/customers/products
- important media and commercial drivers
- correlation or confounding between price, promotion, media and distribution
- whether the requested level of heterogeneity is supported by the data

Do not jump straight from a bad R-hat to tighter priors.

Convergence rule
================
Treat convergence as a property of the chains, not a single number.
Inspect:
- trace plots
- per-chain posterior density overlays for important parameters
- rank R-hat
- bulk and tail ESS
- divergences

If chains occupy visibly different posterior regions, do not use that posterior
as the basis for importance reweighting.

Reference-fit rule
==================
If centred hierarchical parameterisation is causing difficult geometry, first
try the equivalent non-centred hierarchy while preserving the intended prior
distribution.

Only proceed to a sweep once the reference fit is trustworthy enough to
represent the fitted posterior.

Custom-model discovery
======================
Run:

    pmm-sweep inspect <reference-model>

Do not guess prior paths, posterior variable names or dimensions.
Inspect the model_config and posterior of the actual custom PyMC-Marketing 1.x model.
The custom model may use dimensions such as SKU, customer, DMA, product, country
or segment. Preserve those native dimensions.

Sweep workflow
==============
1. Identify the hierarchy or prior that plausibly contributes to weak identification.
2. Preserve its fitted distribution and dimensions unless explicitly asked otherwise.
3. Edit the YAML sweep grid under configs/ rather than hard-coding client priors.
4. Keep Pareto-k and reweighting-ESS guardrails enabled.
5. Protect business-relevant posterior variables, for example:
   - price/control coefficients
   - channel_contribution_original_scale
   - ROI or response parameters if present
6. Run the sweep.
7. Explain which candidates were rejected and why.
8. Rank feasible changed candidates by the smallest prior change first.

Important language
==================
reweight_ess is importance-sampling overlap ESS.
It is NOT predicted NUTS bulk ESS for the future refit.

Do not say the sampler is fixed because a candidate has a high reweighting ESS.
Only the real validation fit can confirm convergence.

Validation
==========
For the recommended candidate:
- emit the exact native PyMC-Marketing 1.x Prior(...) or supported special-prior patch
- run one real validation refit
- check divergences, R-hat, ESS, traces and chain posterior overlays again
- compare protected business quantities with the reference model

For this case study specifically
================================
The target is log_units and:

    price_discount_signal = -log(price / list_price)

so conventional price elasticity is the negative of the posterior coefficient
at control="price_discount_signal".

Do not force all SKU/customer elasticities to be equal. The goal is partial
pooling: retain supported heterogeneity while removing unsupported wandering.

Return
======
1. EDA summary explaining why the model is hard.
2. Clear diagnosis of the original non-convergence.
3. At least one trace and one per-chain posterior overlay for a problematic parameter.
4. Reference-fit convergence table.
5. Sweep results sorted by feasibility and prior distance.
6. Explanation of rejected candidate categories.
7. Exact recommended PyMC-Marketing 1.x prior patch.
8. Before/after business-variable comparison.
9. Final validation convergence table.
10. Any caveats that mean the model should not be promoted.
```
