@damiangilgonzalez/harness 1.3.7

package/skills/research-ops/references/credibility-rubric.md

@@ -0,0 +1,78 @@
+# Credibility rubric — SIFT, CRAAP, lateral reading, confidence tiers
+
+The body picks the check by source type. This is the full walkthrough you offload to when
+a source is borderline.
+
+## SIFT — for web and popular sources
+
+Mike Caulfield's SIFT is fast and built for the open web, where the question is usually
+"can I trust this at all" rather than "is this scholarship sound."
+
+- **Stop.** Before you read or quote, pause. Do you recognize the source? Is your reaction
+  ("this confirms what I wanted") doing the evaluating for you? Stop again whenever you
+  feel certainty arriving too easily.
+- **Investigate the source.** Who published this, and what's their stake? A vendor blog
+  arguing its own product wins is a lead, not a neutral finding. You're not reading the
+  article yet — you're sizing up who wrote it.
+- **Find better coverage.** Don't fixate on the page you landed on. Is there a more
+  authoritative source making the same claim? If the only place a claim appears is one
+  blog, that's a low-confidence claim by definition.
+- **Trace to the original.** Most web claims are re-reports. Follow the chain back to the
+  primary source — the actual filing, paper, release note, dataset. Quote that, with its
+  date, not the re-report.
+
+## CRAAP — for scholarly and formal-document sources
+
+When the source is a paper, standard, regulation, or formal report, evaluate it on its
+merits:
+
+- **Currency** — when was it published or last revised? Is that recent enough for the
+  claim? (A 2021 benchmark is stale for a 2026 performance claim.)
+- **Relevance** — does it actually address your question, or just mention the keyword?
+- **Authority** — who are the authors/issuer, and are they credentialed for this?
+- **Accuracy** — is it evidenced, cited, reproducible? Does it agree with other sources?
+- **Purpose** — inform, sell, persuade, or advocate? Purpose colours which facts get
+  emphasized and which get omitted.
+
+## Lateral reading — the move that does the work
+
+Vertical reading (staying on the page, reading top to bottom, judging it by how
+professional it looks) is how people get fooled. **Lateral reading** is leaving the page
+to judge it:
+
+1. Open a new tab.
+2. Search the author's or organization's name plus "funding", "owned by", "criticism",
+   or the claim itself.
+3. Read what *independent* parties say about them before you trust what they say about
+   themselves.
+
+A polished site, a confident tone, and an "About us" page are presentation, not evidence.
+The org's reputation as reported by others is the evidence.
+
+## Confidence tiers, with worked examples
+
+Assign a tier to every load-bearing claim. Use it in the provenance line.
+
+| Tier | When | Worked example |
+|---|---|---|
+| **High** | Primary/authoritative source, or a claim corroborated across ≥2 independent ones | A regulator's own published rule text, accessed at the source; or two independent reputable outlets reporting the same dated figure |
+| **Medium** | Reputable secondary source, single, plausible but not yet corroborated | A respected trade-press article reporting a number with a date, no second source found yet |
+| **Low** | Single blog/forum/vendor claim, uncorroborated, or no discernible date | One personal blog asserting a benchmark with no methodology and no other source repeating it |
+
+Worked walkthrough:
+
+- **Government filing → High.** You're at the primary source; SIFT's "trace to original"
+  is already satisfied. Cite it with its publication date.
+- **Corroborated trade press → Medium → can rise to High.** One outlet reports a figure;
+  you find a second, independent outlet (not republishing the first) with the same figure
+  and date. Independence is what promotes it; two outlets quoting one wire story stay
+  Medium.
+- **Single blog → Low.** Useful as a lead — it might point you to a primary source worth
+  tracing — but never cite it as the basis for a load-bearing claim. If it's the only
+  thing you can find, the claim itself is low-confidence; say so in the memo.
+
+## Independence test
+
+Two sources are independent only if they don't both derive from the same origin. Three
+articles quoting the same press release are **one** source. Before you call a claim
+triangulated, ask: would these still agree if the one upstream source were wrong?

package/skills/research-ops/references/memo-template.md

@@ -0,0 +1,63 @@
+# Memo template — skeleton + provenance grammar
+
+This is the contract `scripts/verify.sh` checks against. Keep the section headings and the
+provenance line shape, and the gate passes.
+
+## Provenance line grammar
+
+Every finding line carries one of these shapes:
+
+```text
+<CLAIM> — [Source title](https://url), pub 2026-04-12 / accessed 2026-06-02 · confidence: high
+<CLAIM> — corroborated by [A](https://a, 2026-03-01) and [B](https://b, 2026-05-10) · confidence: high
+<CLAIM> — [Source](https://url), pub n/a / accessed 2026-06-02 · confidence: low
+```
+
+Rules:
+
+- A **citation token** is required on every finding: a Markdown link or an explicit URL.
+- A **date** is required: `pub YYYY-MM-DD`, `accessed YYYY-MM-DD`, or both. If the source
+  has no publication date, write `pub n/a` and keep the access date — don't drop the date
+  field entirely.
+- A **confidence tier** token is required: `high`, `med`/`medium`, or `low`.
+- Triangulated claims name ≥2 independent sources, each with its own date.
+
+## Memo skeleton
+
+```markdown
+# Research memo — <question, scoped>
+
+_As of: 2026-06-02 · researcher: <name/agent> · budget: <N searches, M sources read>_
+
+## Answer
+<The direct answer, 2–4 sentences. Bottom line up front. If the honest answer is
+"it depends", state on what.>
+
+## Findings
+- <claim> — [Source title](https://url), pub 2026-04-12 / accessed 2026-06-02 · confidence: high
+- <claim, triangulated> — corroborated by [A](https://a, 2026-03-01) and [B](https://b, 2026-05-10) · confidence: high
+- <weaker claim> — [Blog](https://url), pub n/a / accessed 2026-06-02 · confidence: low
+
+## Disagreements
+- <where sources conflicted; what each said; which you weight higher and why>
+- (If none: "No source-level disagreement found across the N sources read.")
+
+## Open questions / could not verify
+- <what you could not source>
+- <what remains an assumption, flagged as such>
+- <what would settle it if someone spent more budget>
+
+## Sources
+1. [Source title](https://url) — pub 2026-04-12, accessed 2026-06-02 — <one-line what it is / why trusted>
+2. ...
+```
+
+## What "good" looks like
+
+- The **Answer** stands alone — a reader who stops there still got the bottom line.
+- Every **Findings** line is independently checkable: click the link, see the date, see
+  the tier.
+- **Disagreements** is never empty silently — either it lists conflicts or it states none
+  were found.
+- **Open questions** is present even on a confident memo; it's the boundary of the
+  evidence, not an admission of failure.

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 — a customer health score, NPS, catching churn signals before renewal, a cancellation save flow, or a win-back sequence, and reading GRR against NRR. 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.