| name | recovery-strategy |
| description | Apply the recovery decision matrix to a normalized recovery cohort and produce per-record action recommendations (human_outreach, email_with_discount, email_reminder, email_sequence, accept). Run after the cohort is built. Pure rule evaluation — deterministic, zero LLM tokens, re-runnable whenever the YAML changes. |
Recovery Strategy
Applies config/recovery-matrix.yaml to the normalized cohort from recovery-cohort-builder. Evaluates the lost_opportunity_matrix for lost-opportunity records and the abandoned_cart_matrix for abandoned-cart records. No API calls — pure YAML rule evaluation.
Output: recommendation object appended per row
{
"action": "email_with_discount",
"params": { "discount_percent": 20, "coupon_duration_months": 3, "expiry_hours": 48 },
"rationale": "High-value lead cooling off — 20% welcome-back discount with a 48-hour urgency window",
"rule_index": 1,
"value_tier": "high",
"recency_tier": "recent"
}
Supported actions: human_outreach, email_with_discount, email_reminder, email_sequence, accept.
Workflow
1. Run the matrix script:
python <skill-path>/scripts/apply_recovery_matrix.py \
--cohort <workspace>/recovery-runs/<DATE>/cohort-raw.json \
--matrix <workspace>/config/recovery-matrix.yaml \
--output <workspace>/recovery-runs/<DATE>/cohort-recommendations.json
Script logic: buckets lost_value into value tiers and days_since_event into recency tiers from the YAML, then walks the appropriate matrix (lost_opportunity or abandoned_cart) top-to-bottom — first matching rule wins. An empty match: {} is a catch-all; every matrix ends with one.
2. Inspect the summary output for:
- Spike in
human_outreach with priority: urgent → correct and expected for fresh high-value records.
- Any
rule_index: -1 rows → no catch-all in the YAML; stop and alert the user to fix the matrix.
- Records where
value_tier or recency_tier is null → upstream normalization issue; review the cohort.
3. Show the user an action-count summary and a top-10 preview table sorted by lost_value DESC:
| # | Source | Customer | Plan | Lost Value | Days Since | Action | Rationale |
|---|
Confirm the output path before proceeding to the report.
Edge cases
- Missing
lost_value → script defaults to 0, buckets as low; catch-all handles it.
- Missing
days_since_event → script defaults to recency: recent (conservative middle bucket).
- Unknown action name in YAML → passed through unchanged; orchestrator surfaces it.
- No catch-all rule → script emits
rule_index: -1; flag and stop — matrix must be fixed.
- Mixed currencies → script ignores currency when bucketing; flag if multiple currencies detected.
