offer-recommender

name	offer-recommender
description	Apply the retention decision matrix to a classified cohort and produce per-subscription recommendations (discount, pause, downgrade, human_triage, standard_offer, accept). Run after cancel reasons are classified.

Offer Recommender

Applies config/retention-matrix.yaml (pre_churn_matrix or win_back_matrix) to the classified cohort. No API calls — pure rule evaluation, deterministic, re-runnable when YAML changes.

Output: recommendation object appended per row

{
  "action": "discount",
  "params": { "percent": 25, "duration_months": 3 },
  "rationale": "High-LTV, price objection — aggressive discount preserves long-term value",
  "rule_index": 0,
  "ltv_tier": "high",
  "ltd_tier": "veteran"
}

Supported actions: discount, pause, downgrade, human_triage, standard_offer, accept.

Workflow

1. Run the matrix script:

python <skill-path>/scripts/apply_matrix.py \
    --cohort <workspace>/retention-runs/<DATE>/cohort-<type>-classified.json \
    --matrix <workspace>/config/retention-matrix.yaml \
    --cohort-type <pre_churn|post_churn> \
    --output <workspace>/retention-runs/<DATE>/cohort-<type>-recommendations.json

Script logic: buckets ltv (USD) and ltd (days) into tiers from the YAML, walks matrix rules top-to-bottom, first matching rule wins. An empty match: {} is a catch-all — every matrix should end with one.

2. Inspect summary output for:

• Spike in human_triage → new reason bucket not covered by matrix rules.
• Any rule_index: -1 rows → no catch-all; stop pipeline and tell the user.

3. Show the user action-count summary and a top-5 high-MRR preview table. Confirm output path.

Edge cases

• Missing LTV/LTD → script defaults to 0, buckets as low/new; catch-all handles it.
• Unknown action name in YAML → passed through unchanged; orchestrator surfaces it.
• No catch-all rule → script emits rule_index: -1; flag and stop.