rsc-universal 0.1.1

package/skills/research-ops/scripts/verify.sh

@@ -0,0 +1,181 @@
+#!/usr/bin/env bash
+#
+# verify.sh — provenance gate for the `research-ops` skill.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static checks over a produced research memo (Markdown). It validates that the
+#   memo is SOURCED, DATED, and REVIEW-READY — never whether the answer is correct.
+#   For each memo found:
+#     1. Structure: an Answer/Summary section AND an Open-questions/Unverified
+#        section both exist. A memo with no stated boundary of the evidence fails.
+#     2. Findings carry citations: under the Findings section, lines that state a
+#        claim carry a citation token (a Markdown link or a bare URL).
+#     3. Dates: every cited finding line carries a date — YYYY-MM-DD, "pub", or
+#        "accessed". An undated citation is a fail.
+#     4. Confidence: a confidence tier token (high|med|medium|low) appears among
+#        the findings. A memo that never tiers its claims fails.
+#
+#   A missing/empty target is a SKIP, never a failure. grep/awk only; no network.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                      # scan ./ for *memo*/*research* .md
+#   ./verify.sh --path memo.md       # check one memo
+#   ./verify.sh --path research/     # scan a directory of memos
+#   ./verify.sh --strict             # treat warnings as failures (CI gate)
+#
+# EXIT CODES
+#   0  clean, empty target, or warnings only without --strict
+#   1  a real failure (no answer section, undated citation, no confidence tier)
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+usage() { sed -n '2,34p' "$0" | sed 's/^# \{0,1\}//'; }
+
+SCAN_PATH="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)    SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    --strict)  STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+summary() { printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"; }
+
+if [ ! -e "$SCAN_PATH" ]; then
+  printf '%s[skip]%s path not found: %s — nothing to check\n' "$YELLOW" "$NC" "$SCAN_PATH"
+  skip_count=1; summary; exit 0
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+if ! have awk; then
+  printf '%s[skip]%s awk not found — cannot parse memo\n' "$YELLOW" "$NC"
+  skip_count=1; summary; exit 0
+fi
+
+# Collect candidate memo files: prefer named memos/research files, else any .md.
+FILES=""
+if [ -f "$SCAN_PATH" ]; then
+  FILES="$SCAN_PATH"
+else
+  FILES="$(find "$SCAN_PATH" -type f -name '*.md' \( -iname '*memo*' -o -iname '*research*' -o -iname '*findings*' \) 2>/dev/null || true)"
+  if [ -z "$FILES" ]; then
+    FILES="$(find "$SCAN_PATH" -type f -name '*.md' 2>/dev/null || true)"
+  fi
+fi
+
+if [ -z "$FILES" ]; then
+  printf '%s[skip]%s no research memo found under %s — nothing to check (clean)\n' "$YELLOW" "$NC" "$SCAN_PATH"
+  skip_count=1; summary; exit 0
+fi
+
+# check_one <file>: one awk pass emits "LEVEL message" lines; the shell tallies.
+check_one() {
+  f="$1"
+  [ -s "$f" ] || { printf '%s[skip]%s empty file: %s\n' "$YELLOW" "$NC" "$f"; return; }
+  printf '%s—— %s%s\n' "$YELLOW" "$f" "$NC"
+
+  awk '
+    # BSD awk: no IGNORECASE, no \b. Lowercase with tolower(); explicit boundaries.
+    {
+      lc=tolower($0)
+
+      # --- section detection (headings) ---
+      if (lc ~ /^#+/) {
+        infind=0
+        if (lc ~ /(answer|summary|bottom line|tl;dr|tldr)/) hasanswer=1
+        if (lc ~ /(open question|unverified|could not verify|couldnt verify|not verified|limitations)/) hasopen=1
+        if (lc ~ /(finding|claim|evidence)/) infind=1
+      }
+
+      # --- a finding line: a bullet/numbered claim, inside findings or anywhere ---
+      isbullet = ($0 ~ /^[ \t]*([-*]|[0-9]+\.)[ \t]+/)
+      if (isbullet && (infind || lc ~ /confidence:/)) {
+        findlines++
+        haslink = ($0 ~ /\]\(http/ || $0 ~ /https?:\/\//)
+        hasdate = ($0 ~ /(19|20)[0-9][0-9]-[0-1][0-9]-[0-3][0-9]/ || lc ~ /pub /|| lc ~ /accessed/ || lc ~ /pub n\/a/)
+        if (haslink) {
+          citedlines++
+          if (!hasdate) {
+            undated++
+            if (undated <= 3) print "DETAIL cited finding with no date: " substr($0,1,80)
+          }
+        } else {
+          uncited++
+          if (uncited <= 3) print "DETAIL finding with no citation token: " substr($0,1,80)
+        }
+      }
+
+      if (lc ~ /confidence: *(high|med|medium|low)/) tiers++
+    }
+    END {
+      if (hasanswer) print "OK answer/summary section present"
+      else           print "FAIL no Answer/Summary section found"
+
+      if (hasopen) print "OK open-questions/unverified section present"
+      else         print "FAIL no Open-questions/Unverified section found"
+
+      if (findlines == 0) {
+        print "WARN no finding/claim bullet lines detected — nothing to check provenance on"
+      } else {
+        if (uncited > 0) print "FAIL "uncited" finding line(s) carry no citation token"
+        else             print "OK every finding line carries a citation token ("citedlines" cited)"
+
+        if (undated > 0) print "FAIL "undated" cited finding(s) carry no date"
+        else if (citedlines > 0) print "OK "citedlines" cited finding(s); all dated"
+
+        if (tiers > 0) print "OK "tiers" confidence tier token(s) present"
+        else           print "FAIL no confidence tier (high|med|low) found on any finding"
+      }
+    }
+  ' "$f" 2>/dev/null
+}
+
+printf 'Checking research memos under: %s\n\n' "$SCAN_PATH"
+printf '%s\n' "$FILES" | while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  check_one "$f"
+done > "/tmp/ro_verify.$$" 2>&1 || true
+
+while IFS= read -r line; do
+  case "$line" in
+    FAIL*)   printf '%s[fail]%s %s\n' "$RED"    "$NC" "${line#FAIL }" ;;
+    WARN*)   printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "${line#WARN }" ;;
+    OK*)     printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "${line#OK }" ;;
+    DETAIL*) printf '        %s\n' "${line#DETAIL }" ;;
+    *)       printf '%s\n' "$line" ;;
+  esac
+done < "/tmp/ro_verify.$$"
+
+tally() { { grep -c "$1" "/tmp/ro_verify.$$" 2>/dev/null || true; } | tr -dc '0-9'; }
+fail_count=$(tally '^FAIL'); fail_count=${fail_count:-0}
+warn_count=$(tally '^WARN'); warn_count=${warn_count:-0}
+ok_count=$(tally '^OK');     ok_count=${ok_count:-0}
+sk=$(tally '\[skip\]');      skip_count=$((skip_count + ${sk:-0}))
+rm -f "/tmp/ro_verify.$$" 2>/dev/null || true
+
+summary
+
+cat <<'EOF'
+
+Note: this gate proves the memo is SOURCED, DATED, and REVIEW-READY (answer section,
+cited + dated findings, confidence tiers, an open-questions section). It does NOT judge
+whether the answer is correct — that is the capability eval's and the researcher's job.
+Re-run with --strict to gate CI on a clean pass.
+EOF
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/retention/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: retention
+description: "Use when revenue is leaking out the bottom of the funnel and you need a program to keep, score, and win back customers — building a customer health score, running NPS, catching churn signals before renewal, designing a cancellation save flow, or a win-back sequence. Triggers: 'reduce churn', 'health score', 'NPS', 'save play', 'cancellation flow', 'win-back', 'at-risk accounts', 'GRR vs NRR', non-obvious 'my annual customers are downgrading to monthly', 'renewal is slipping', 'detractors keep canceling'; Catalan/Spanish 'reduir la rotació de clients', 'recuperar clients perduts', 'puntuació de salut del client', 'evitar bajas'. NOT working a single live churn-risk ticket in the moment (that is customer-support), NOT the first-30-days welcome flow (that is client-onboarding)."
+tags: [retention, churn, nps, health-score, save-play, win-back, nrr, grr, customer-success]
+recommends: [customer-support, client-onboarding, unit-economics, pricing, forecasting, compliance, newsletter, review-management]
+origin: risco
+---
+
+# Retention
+
+You run retention as a *program*, not as a reaction. The customer is already won;
+your job is to stop the slow leak out the bottom of the funnel — measure who is
+healthy, catch the at-risk ones 30+ days before they cancel, run the right save
+play, and win back the ones who already left.
+
+This is the program layer. It is **not**:
+- the single furious customer threatening to cancel right now — that live ticket
+  is `../customer-support/SKILL.md`.
+- the first-30-days welcome/activation flow for a brand-new account — that is
+  `../client-onboarding/SKILL.md`. Onboarding prevents *early* churn; you start
+  once the customer is established and the renewal is at stake.
+
+## What you produce
+
+Three decision artifacts — judgment, not prose:
+
+1. **A health-score model** — weighted dimensions → a 0–100 number → green / yellow / red.
+2. **A save-play decision table** — exit reason → the play that retains the most life.
+3. **A win-back cadence** — a 30/60/90-day ladder with an escalating offer.
+
+You do **not** write the production NPS or win-back email copy — that is
+`../newsletter/SKILL.md`. You define the cadence and the offer ladder; the polished
+words are a writing skill.
+
+## The retention loop (the spine)
+
+Work these five steps in order. Each one feeds the next.
+
+1. **Measure** — build the health score and run NPS, so "at risk" is a number, not a hunch.
+2. **Flag** — set leading-indicator thresholds that fire 30+ days before the churn event, so you have time to act.
+3. **Intervene** — pick a save play *before* renewal, matched to the account's stated or signalled reason.
+4. **Recover** — run a win-back sequence on the ones who left anyway.
+5. **Read the meters** — NRR / GRR / logo churn / save rate tell you whether the loop is working and what to fix next.
+
+## Build the health score
+
+A single signal lies. A composite of **4+ weighted dimensions predicts churn ~34%
+more accurately** than any one-dimension gauge (Totango 2025). Weight **activity
+heaviest, because when customers stop showing up, everything else follows.**
+
+Default weighting to start from, then tune to your product:
+
+| Dimension | Weight | Example signals |
+|---|---|---|
+| Product usage / activity | ~40% | login recency, sessions/week, depth of feature adoption |
+| Engagement | ~25–30% | response to emails, QBR attendance, champion still employed |
+| Milestones / business fit | ~20% | onboarding goals hit, ROI realized, plan vs need match |
+| Recency | ~10% | days since last meaningful action |
+
+Normalize each dimension to 0–100, multiply by its weight, sum to one 0–100 score.
+Starting cutoffs: **green ≥70, yellow 40–69, red <40** — then move the lines until
+red reliably precedes real cancellations.
+
+```text
+Bad:  "Logins dropped, flag the account."   (one signal, fires late or false)
+Good: usage 30/100×0.40 + engagement 60×0.28 + fit 80×0.20 + recency 20×0.10
+      = 12 + 16.8 + 16 + 2 = 46.8 → yellow, worth a touch this week
+```
+
+The full dimension catalog, the normalization recipe, cutoff tuning, and a fully
+worked scored account live in `references/health-score-and-metrics.md`.
+
+## NPS done right
+
+NPS = **%Promoters − %Detractors** on an 11-point 0–10 scale. Promoters 9–10,
+Passives 7–8 (dropped from the math), Detractors 0–6. >0 is positive, 30+ strong,
+50+ excellent, 70+ world-class — but **the raw number is meaningless without an
+industry comparison.** Run it two ways:
+
+- **Relational** — quarterly or annual, a pulse on the whole base.
+- **Transactional** — fires right after a specific interaction (support close,
+  onboarding done).
+
+```text
+Bad:  Collect NPS, put 42 on a dashboard, move on.
+Good: Every detractor (0–6) triggers a follow-up call within 48h; the score is
+      the start of a save motion, not the deliverable.
+```
+
+## Leading indicators & the flag
+
+The threshold must buy **30+ days of lead time** — flag early enough to actually
+intervene. Strongest signals, in roughly the order they predict:
+
+- **days since last login** (the clearest "they left mentally already")
+- **feature-adoption depth shrinking** (using less of what they pay for)
+- **support-ticket velocity *rising*** — more tickets predict churn, not fewer
+- **billing-cadence downgrade: annual → monthly is an early churn tell**, not a neutral preference
+- seat contraction, repeated payment failures
+
+The last two are the non-obvious ones. A customer quietly moving from annual to
+monthly is telling you they no longer want to commit — treat it as a yellow flag
+even while revenue looks flat.
+
+## Save plays — the decision table
+
+This is where the flow genuinely branches. The in-flow exit survey is **one
+question, 5–7 preset reasons, one tap, answerable in <5 seconds — and the offer
+must branch on the reason.** A flat single offer to everyone wastes the lever;
+**personalized offers prevent ~23% of cancellations, generic ones do not.**
+
+Rank plays by **retained life, not by gut.** Industry-average save rate ≈34%
+(Churnkey 2025).
+
+| Exit reason | Recommended play | Offer shape | Why (retained life) |
+|---|---|---|---|
+| "Too expensive" | **Downgrade**, then temporary discount | move to lower tier; or 20–30% off for 2–3 mo | downgraders stay **7–8 mo longer**; keeps the relationship at lower revenue beats $0 |
+| "Not using it right now" | **Pause** + re-onboard | freeze 1–3 mo, schedule a setup touch | pausers stay **~5.5 mo longer**; ~25% of would-be churners pause instead of cancel |
+| "Missing a feature" | **Human / roadmap** | show roadmap, connect to PM, no discount | tests real demand; a discount does not fix a capability gap |
+| "Switching vendor" | **Save call** | book a human conversation fast | only a person can counter a competitor decision |
+| Price-only, no fit | **Graceful let-go** | clean cancel + win-back enrollment | bad-fit retention just delays churn and inflates support cost |
+
+Order of preference when the reason is fuzzy: **downgrade > pause > temporary
+discount > human save call > let-go.** Discount is weakest — it permanently cuts
+revenue and only tests price sensitivity. Use **temporary 20–30% off for 2–3
+months, never a permanent cut.**
+
+Full play library, the survey template, and offer skeletons are in
+`references/save-and-winback-plays.md`.
+
+## Win-back cadence
+
+For customers who left anyway. A 30/60/90 ladder recovers **~5–15% of lost
+customers.** Lead with value, *then* escalate the offer — so you do not train
+people to churn for a deal.
+
+```text
+Day 30 — value reminder, NO discount ("here's what's new / what you're missing")
+Day 60 — modest incentive: ~15–20% off for 3 months
+Day 90 — best offer: ~30–40% off for 6 months
+```
+
+Guardrail: if Day 30 leads with the discount, your healthy customers learn that
+cancelling is how you get a better price. Always value-first.
+
+## Read the meters
+
+| Metric | What it is | What it tells you |
+|---|---|---|
+| **NRR** | net revenue retention, includes expansion | can exceed 100%; 2025 B2B median ~106% |
+| **GRR** | gross revenue retention, contraction + churn only | cannot exceed 100%; median ~90% |
+| **Logo churn** | % of *customers* lost, each weighted equally | base erosion |
+| **Revenue churn** | % of *dollars* lost | concentration risk |
+| **Save rate** | % of cancel attempts saved | benchmark ≈34% |
+
+The alarm: **if GRR < 80%, a few expanding accounts are masking a fundamental
+retention failure — NRR is lying to you.** Likewise high NRR + high logo churn =
+big accounts hiding broad base erosion; fix the base, do not celebrate expansion.
+
+Mini decision:
+- High logo churn + high NRR → fix the base (health score + save plays), not expansion.
+- GRR < 80% → stop everything else; the product or fit is leaking.
+- 43% of SMB losses happen in the first 90 days → that is a `client-onboarding`
+  problem, not yours.
+
+Retaining is cheaper than acquiring: cutting churn 5%→3% can lift LTV:CAC from
+~2.5:1 to ~4:1 with **zero** extra acquisition spend. For the LTV/CAC/payback
+model itself, hand off to `../unit-economics/SKILL.md`; for forecasting MRR from
+the churn rate, `../forecasting/SKILL.md`.
+
+## Compliance guardrail
+
+Build the save flow so a frustrated user can **always reach cancel in one click.**
+
+The law here is unsettled — **do not hard-code "the law."** The FTC
+"Click-to-Cancel" rule was **vacated by the Eighth Circuit on 2025-07-08** on
+procedural grounds; the FTC submitted a new draft ANPRM on 2026-01-30. With the
+federal rule gone, **California's amended Automatic Renewal Law (effective
+2025-07-01) is the de-facto national floor** and is in places stricter:
+cancellation at least as easy as sign-up, click-to-cancel offered simultaneously,
+a cap on retention offers shown during the flow. Treat CA ARL as the floor and
+defer the actual legal text to `../compliance/SKILL.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Discount-first save play | permanently cuts revenue, only tests price | rank downgrade > pause > temporary discount |
+| One flat offer for every exit reason | wastes the lever; generic prevents ~0 vs ~23% personalized | branch the offer on the stated reason |
+| Single-signal health score ("logins down") | misses ~34% accuracy; fires late or false | 4+ weighted dimensions, activity heaviest |
+| Collect NPS, then ignore it | a number on a dashboard saves no one | every detractor triggers a 48h follow-up |
+| Optimize NRR while logo churn bleeds | expansion masks base erosion | watch GRR; GRR<80% is the alarm |
+| Dark-pattern cancel flow (cancel buried) | illegal under CA ARL, breeds public detractors | cancel reachable in one click, always |
+| Win-back that leads with the discount | trains healthy customers to churn for a deal | Day 30 value-only, escalate later |
+| Treating first-90-day churn as a retention problem | it is an activation problem | route to `../client-onboarding/SKILL.md` |
+
+## Cross-references
+
+- `../customer-support/SKILL.md` — the single live churn-risk ticket in the moment.
+- `../client-onboarding/SKILL.md` — the first-30-days welcome / activation flow.
+- `../unit-economics/SKILL.md` — the LTV / CAC / payback model.
+- `../pricing/SKILL.md` — how deep a discount can go without breaking margin.
+- `../forecasting/SKILL.md` — projecting MRR/ARR from the churn rate.
+- `../compliance/SKILL.md` — the actual cancellation-law text.
+- `../newsletter/SKILL.md` — production NPS / win-back email copy.
+- `../review-management/SKILL.md` — responding when a detractor posts publicly.

package/skills/retention/evals/README.md

@@ -0,0 +1,13 @@
+# Evals — retention
+
+These cases check three things, and can be run by the skill-eval harness or read
+manually. First, that the description **triggers** on the six retention phrasings
+in `should_trigger` (including the non-obvious annual→monthly-downgrade prompt and
+the Catalan/Spanish ones). Second, that it stays **silent** on the four near-misses
+in `should_not_trigger`, each of which should route to the named real sibling
+(`customer-support`, `client-onboarding`, `unit-economics`, `pricing`). Third, that
+a model following `SKILL.md` hits the `capability` rubric on the GRR-78% scenario —
+flagging the GRR alarm, building a weighted health score, replacing the flat
+discount with a branched save table, adding a value-first win-back, and keeping
+cancel one-click reachable. No network, fixtures, or credentials are needed; this
+is a process skill with no checkable artifact, so there is no `verify.sh`.

package/skills/retention/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: retention
+
+should_trigger:
+  - prompt: "Our churn is climbing and I want to build a customer health score."
+    why: Core trigger — designing the weighted health-score model is the skill's first artifact.
+  - prompt: "Set up NPS and turn the detractors into a save motion."
+    why: NPS branch — the skill owns the formula, bands, and the detractor follow-up motion.
+  - prompt: "Design a cancellation flow with the right save offer per reason."
+    why: Save-play branch — the exit-reason decision table is the core deliverable.
+  - prompt: "A bunch of my annual customers just switched to monthly — is that a problem?"
+    why: Non-obvious — tests the annual→monthly downgrade leading-indicator fact; not phrased as a retention question at all.
+  - prompt: "Vull recuperar clients que ens han deixat fa dos mesos."
+    why: Catalan win-back trigger ("I want to win back customers who left two months ago") — maps to the 30/60/90 ladder.
+  - prompt: "Quiero reducir las bajas y montar un programa de retención."
+    why: Spanish — "reduce cancellations and stand up a retention program"; core program-level trigger.
+
+should_not_trigger:
+  - prompt: "This customer is furious and threatening to cancel right now, draft my reply."
+    route_to: customer-support
+    why: A single live churn-risk ticket in the moment; retention designs the program, support works the ticket.
+  - prompt: "Build the first-week welcome and activation flow for new signups."
+    route_to: client-onboarding
+    why: The onboarding window for brand-new accounts, not established at-risk customers.
+  - prompt: "Model our LTV:CAC and payback across the whole funnel."
+    route_to: unit-economics
+    why: The blended unit-economics model; retention uses churn as an input but does not build it.
+  - prompt: "How deep can I discount the win-back offer before it kills margin?"
+    route_to: pricing
+    why: The margin floor on a discount; retention decides whether to offer, pricing decides how deep.
+
+capability:
+  - scenario: >
+      An operator runs a SaaS with GRR 78%, NRR 109%, rising logo churn, and a flat
+      "20% off" shown to everyone in the cancellation flow. They ask how to fix retention.
+    must_include:
+      - Flags GRR < 80% as a base-erosion alarm and names that NRR 109% is masking it.
+      - Builds a 4+ dimension health score weighting product activity heaviest (~40%).
+      - Replaces the flat discount with an exit-reason decision table.
+      - Ranks save plays downgrade > pause > temporary discount (not discount-first).
+      - Adds a 30/60/90 win-back ladder that leads with value, not the deal.
+      - Keeps the cancel path reachable in one click (CA ARL compliance floor).
+      - Does NOT simply deepen or widen the existing discount.

package/skills/retention/references/health-score-and-metrics.md

@@ -0,0 +1,97 @@
+# Health score & retention metrics
+
+The long lookup material most operators consult once when standing the program up.
+
+## Dimension catalog
+
+Pick **4+** dimensions. A composite of 4+ weighted signals predicts churn ~34%
+more accurately than a single-dimension gauge (Totango 2025). Weight activity
+heaviest — absence precedes every other failure.
+
+| Dimension | Default weight | Candidate signals | Notes |
+|---|---|---|---|
+| Product usage / activity | ~40% | login recency, sessions/week, DAU/WAU, depth of feature adoption, % of seats active | the dominant predictor; under-weight it and the score lags reality |
+| Engagement | ~25–30% | email open/reply, QBR attendance, NPS response, champion still employed, community presence | the relationship layer |
+| Milestones / business fit | ~20% | onboarding goals hit, first value realized, ROI demonstrated, plan matches stated need | "are they getting what they bought?" |
+| Recency | ~10% | days since last meaningful action | a fast decay signal that sharpens the others |
+
+Add product-specific dimensions (e.g. integration depth, API call volume) by
+splitting a category's weight — keep the total at 100.
+
+## Normalize to 0–100
+
+For each dimension, map the raw signal onto 0–100 before weighting:
+
+```text
+1. Define the healthy range per signal (e.g. logins/week: 0 = none, 5+ = full).
+2. Linear-scale the raw value into 0–100 within that range, clamp at the ends.
+3. If a dimension has several signals, average their 0–100 scores first.
+4. Multiply each dimension's 0–100 by its weight, sum → the account score.
+```
+
+## Cutoff tuning
+
+Starting cutoffs: **green ≥70, yellow 40–69, red <40.**
+
+Tune them against history: pull the last ~2 quarters of cancellations, score each
+account at "30 days before they churned," and move the red line until most real
+churners were already red or yellow at that point. If everything was green until
+the day they left, your dimensions or weights are wrong — usually activity is
+under-weighted.
+
+## Worked scored account
+
+```text
+Account: Acme Co, mid-market, renewal in 45 days
+
+Usage      30/100  × 0.40 = 12.0   (logins halved, two features abandoned)
+Engagement 60/100  × 0.28 = 16.8   (champion still replies, missed last QBR)
+Fit        80/100  × 0.20 = 16.0   (hit onboarding goals, ROI shown)
+Recency    20/100  × 0.10 =  2.0   (last meaningful action 18 days ago)
+                              -----
+Score = 46.8  →  YELLOW
+
+Read: usage is collapsing while the relationship is intact — classic "not using
+it" pattern. Play: pause + re-onboard touch, not a discount. Flag now: 45 days
+of lead time is exactly the window the score is meant to buy.
+```
+
+## Metrics reference
+
+### Formulas
+
+```text
+GRR = (start MRR − contraction − churn) / start MRR        (never > 100%)
+NRR = (start MRR − contraction − churn + expansion) / start MRR   (can be > 100%)
+Logo churn    = customers lost in period / customers at start
+Revenue churn = MRR lost in period / MRR at start
+Save rate     = cancel attempts saved / total cancel attempts
+```
+
+### Worked numbers
+
+```text
+Start MRR 100k; expansion +15k; contraction −5k; churned −12k.
+GRR = (100 − 5 − 12) / 100 = 83%
+NRR = (100 − 5 − 12 + 15) / 100 = 98%
+
+Read: NRR 98% looks fine, but GRR 83% is barely above the 80% alarm line —
+expansion is papering over real base loss. Optimize the base, not upsell.
+```
+
+### Segment benchmark table (2025 B2B SaaS)
+
+| Segment | NRR | Monthly logo churn | Annual churn |
+|---|---|---|---|
+| SMB | ~97% | 3–7% | ≈31–58% |
+| Mid-market | ~108% | 1.5–3% | — |
+| Enterprise | ~118% | <1.5% | — |
+| "Good" benchmark | NRR median ~106%, GRR median ~90% | <1%/mo | <5%/yr |
+
+The alarm restated: **GRR < 80% means a few expanding accounts are masking a
+fundamental retention failure.** And **43% of SMB losses happen in the first 90
+days** — that early window is an activation problem (`../client-onboarding/SKILL.md`),
+not a renewal-program problem.
+
+Sources: Totango 2025, customerscore.io, SaaS Capital, Fiscallion, ChurnZero,
+Vena, Vitally, Optifai, Churnkey 2025 — accessed 2026-06-02.

package/skills/retention/references/save-and-winback-plays.md

@@ -0,0 +1,65 @@
+# Save plays & win-back ladder
+
+A ready-to-lift playbook. The skeletons below are structure and offer shape — not
+finished copy. Polished email/in-app wording is `../newsletter/SKILL.md`.
+
+## The one-question exit survey
+
+Rules:
+- **One question, 5–7 preset reasons, one tap, answerable in <5 seconds.**
+- Always show a free-text "other" but branch on the preset.
+- The cancel button stays reachable in one click throughout (CA ARL floor — see
+  `../compliance/SKILL.md`).
+
+```text
+Before you go — what's the main reason?
+  ( ) Too expensive
+  ( ) Not using it right now
+  ( ) Missing a feature I need
+  ( ) Switching to another tool
+  ( ) Just a temporary project / seasonal
+  ( ) Something else ____________
+```
+
+## Save-play library (exit reason → ranked play)
+
+Ranked by retained life. Save rate benchmark ≈34% (Churnkey 2025). Personalized
+offers prevent ~23% of cancellations; generic flat offers do not.
+
+| Exit reason | Play 1 | Play 2 | Offer shape | Retained-life rationale |
+|---|---|---|---|---|
+| Too expensive | Downgrade to lower tier | Temporary discount | tier move; or 20–30% off, 2–3 mo | downgraders stay **7–8 mo longer**; lower revenue > $0 |
+| Not using it right now | Pause | Re-onboarding touch | freeze 1–3 mo + scheduled setup call | pausers stay **~5.5 mo longer**; ~25% of would-be churners pause |
+| Missing a feature | Human / roadmap | — | connect to PM, show roadmap, NO discount | money does not close a capability gap |
+| Switching vendor | Save call | — | book a person fast | only a human counters a competitor decision |
+| Temporary / seasonal | Pause | Downgrade | freeze to reactivation date | preserves the account for the obvious return |
+| Bad fit / price-only | Graceful let-go | — | clean cancel + enroll in win-back | retaining bad fit just delays churn, inflates support |
+
+Tie-breaker when the reason is fuzzy: **downgrade > pause > temporary discount >
+human save call > let-go.** Discount last — it permanently cuts revenue and only
+tests price sensitivity. **Temporary 20–30% off for 2–3 months, never permanent.**
+
+Pause economics worth remembering: pause programs generate $200M+ in industry
+re-subscription revenue precisely because ~25% of cancellers will accept "freeze"
+when they would have rejected "stay."
+
+## Win-back ladder (30 / 60 / 90)
+
+For customers who left anyway. Recovers ~5–15%. Value-first, then escalate — never
+lead with the deal or you train healthy customers to churn for a discount.
+
+```text
+Day 30  Value reminder. NO discount.
+        "Here's what's shipped / what your team is missing." Re-open the door.
+
+Day 60  Modest incentive.
+        ~15–20% off for 3 months. "Come back and pick up where you left off."
+
+Day 90  Best offer.
+        ~30–40% off for 6 months. Final, time-boxed. "Last chance at this rate."
+```
+
+After Day 90, drop to a low-frequency nurture (quarterly product news) — do not
+keep escalating discounts indefinitely.
+
+Sources: Churnkey 2025, Recurly, SmartSMS, Userpilot, ChurnWard — accessed 2026-06-02.