@aria_asi/cli 0.2.39 → 0.2.41

package/skills/aria-cognition/aria-research-orchestrator/references/research-patterns.md

@@ -0,0 +1,270 @@
+# Research Orchestrator Cookbook — Decomposition, Sourcing, Synthesis Patterns
+
+> Loaded by `aria-research-orchestrator` for external evidence acquisition.
+
+## 1. The Question Decomposition Frame
+
+Before any fetch, decompose the research request into 2-5 sub-questions, each with:
+- A specific source class (primary / secondary / tertiary)
+- A freshness window (how recent does the source need to be)
+- A success criterion (what answer would resolve this)
+
+### Example decomposition
+**Vague request:** "Research Linear vs Asana vs Jira"
+
+**Decomposed:**
+1. **Pricing at 10-50 seats** — primary (vendor pricing pages), freshness 30 days, success: dollar amount per seat per month at each tier
+2. **Reviews mentioning onboarding friction** — secondary (G2, Capterra, Reddit), freshness 90 days, success: 5+ recent reviews with onboarding-specific content
+3. **Market share / dominant choice for SMB SaaS** — secondary/tertiary (industry reports, LinkedIn polls, podcast mentions), freshness 6 months, success: aggregated signal from ≥3 sources
+4. **Public roadmap signals** — primary (vendor blogs, changelog), freshness 60 days, success: feature direction known
+
+Now each can be fetched with the right tool and verified.
+
+## 2. The Source Class Hierarchy
+
+### Primary sources (highest authority)
+- Official docs, specs, RFCs (e.g., MCP spec, WCAG 2.2)
+- SEC filings, financial filings (10-K, 10-Q, S-1)
+- Vendor pricing pages, official changelog
+- First-party blog posts (vendor's own engineering / product blog)
+- Source code itself (GitHub repos, package READMEs)
+
+**When to use**: facts, contracts, specifications. Authoritative on what something IS.
+
+### Authoritative-secondary sources
+- Industry analyst reports (Gartner, Forrester, ARK Invest, Bessemer)
+- Peer-reviewed academic research (use `search_vertical(vertical='academic')`)
+- Named-author technical blog posts (the author's reputation is the warrant)
+- Industry benchmark reports (KeyBanc SaaS, OpenView PLG, Battery Ventures)
+
+**When to use**: synthesis, trends, benchmarks. Authoritative on aggregated patterns.
+
+### Aggregated-secondary sources
+- Review sites (G2, Capterra, TrustRadius)
+- Comparison sites (sites that systematically compare vendors)
+- Well-curated awesome-lists on GitHub (community-vetted)
+
+**When to use**: comparative info, customer-voice signals. Authoritative on aggregated user opinion.
+
+### Tertiary / signal sources
+- Social media (X, LinkedIn, Reddit)
+- Forum threads (Hacker News, dev forums)
+- Podcast transcripts
+- Discord / Slack community archives
+
+**When to use**: customer-language harvesting (what words do users use), sentiment direction, early-signal trends. NOT authoritative for facts.
+
+## 3. The Freshness Match
+
+Different research questions have different freshness requirements:
+
+| Question type | Freshness window | Why |
+|---|---|---|
+| Pricing | 30 days | Vendors change pricing frequently |
+| Market data / SaaS metrics | 90-180 days | Quarterly reports common; older data still relevant |
+| Regulatory / legal | 6 months | Slower-moving but checks every 6 months |
+| Tech specs / RFCs | Indefinite if canonical | Older spec is the spec; check version |
+| Competitive feature comparison | 60 days | Roadmaps move quickly |
+| News / current events | 7 days max | News by definition |
+| Academic research | Indefinite if cited | Citation count > recency for foundational |
+| Customer reviews | 90 days | Older reviews may not reflect current product |
+
+### The freshness check primitive
+```typescript
+function isStillFresh(source: Source, question: QuestionType): boolean {
+  const limit = FRESHNESS_WINDOWS[question];
+  const ageDays = (Date.now() - source.publishedAt) / (1000 * 60 * 60 * 24);
+  return limit === Infinity || ageDays <= limit;
+}
+```
+
+If the freshest available source is past the window, EITHER expand the search OR explicitly mark as "no current data; using closest available" with the date.
+
+## 4. The Tool Mapping
+
+| Sub-question shape | Tool | When |
+|---|---|---|
+| "What does this URL say?" | `fetch_url` with prompt | Need extracted info from a known page |
+| "What's currently true about X?" (broad) | `search_web` with 2-3 keyword queries | Need ranked results across the web |
+| "Find papers / specs on X" | `search_vertical(vertical='academic')` | First-party technical/scientific sources |
+| "Find product / pricing for X" | `search_vertical(vertical='shopping')` | Comparison + pricing |
+| "Find people who do X at Y" | `search_vertical(vertical='people')` | Hiring / partnership / interview research |
+| "Show me images / videos of X" | `search_vertical(vertical='image' or 'video')` | Design research, demo research |
+| "I need to actually USE this site" | `browser_task` | Login, fill form, multi-step interaction |
+| "Compare 10+ entities" | `wide_research` or `wide_browse` | Batch processing (cost gate at 20+) |
+
+### Query writing rules
+- **Natural phrases, not keyword lists**: "INP optimization 2025 production" beats "INP perf web vital fast 2025"
+- **Time-sensitive queries include date**: "OWASP Top 10 2025" not "OWASP Top 10 latest"
+- **Multi-entity queries split parallel**: 3 separate queries about 3 vendors beats 1 query mentioning all 3
+- **No quotes** unless exact-match required (fuzzy matching usually better)
+- **Max 3 queries per call** (efficiency)
+
+## 5. The Verification Cycle
+
+For each non-trivial claim, verify with ≥2 independent sources OR explicitly mark as single-sourced.
+
+### Verification levels
+- **Cross-verified** (2+ independent sources agree) — confident; cite both
+- **Authoritative-single** (one primary source) — confident; cite the primary
+- **Single-secondary** (one secondary source) — flag uncertainty; cite the source
+- **Triangulated** (multiple sources directionally agree but specifics differ) — cite range
+
+### Anti-patterns
+- Citing 3 secondary sources that all reference the same primary (still single-sourced)
+- Citing tertiary as if primary
+- Burying single-sourced claims in a list of cited claims (mark them explicitly)
+
+## 6. The Synthesis Back-to-Caller Pattern
+
+Research output is NOT the final answer. Hand verified evidence back to the calling skill in its native format.
+
+### For aria-revenue-engine
+```markdown
+## Research synthesis — feeding to aria-revenue-engine
+
+**Sub-question 1: Linear pricing at 10-50 seats**
+- $8/seat/month (Standard), $14/seat/month (Plus) — [Linear pricing page](https://linear.app/pricing), 2026-05
+- 10% annual prepay discount
+
+**Sub-question 2: Asana pricing**
+- $10.99/seat/month (Premium), $24.99/seat/month (Business) — [Asana pricing](https://asana.com/pricing), 2026-05
+
+**Sub-question 3: SMB market share signal**
+- Linear dominant in startup / dev-team segments per multiple 2024-2025 podcast transcripts
+- Asana dominant in non-engineering teams per G2 2025 review aggregation
+
+**Confidence:** sub-questions 1+2 high (primary sources, current); sub-question 3 medium (secondary signal, directional)
+
+**Hand-off note for aria-revenue-engine:** Linear's $8 entry point sets the SMB ceiling for direct competitors. If our PM-tool product targets startup engineering teams, pricing above Linear's Plus tier ($14) requires explicit feature differentiation, not parity-with-premium positioning.
+```
+
+### For aria-gtm-architect
+Pass the buyer-language samples + competitive positioning data:
+```markdown
+## Buyer language samples (for message-fit work)
+
+From G2 reviews of Linear (last 90 days, 5 highest-rated):
+- "I lose less time switching contexts between PRs and tasks"
+- "My team finally agrees on what 'in progress' means"
+- "We stopped having Slack-only updates that nobody could find later"
+
+From Reddit r/startups thread on PM tools (Apr 2026):
+- "Notion is for docs; Linear is for actually shipping"
+- "Stopped using Asana when our eng team revolted"
+
+**Pattern**: buyer language emphasizes shipping speed + clarity + cross-functional alignment, NOT feature lists.
+```
+
+## 7. The Memory-First Discipline (Noor recognition)
+
+Research is expensive; memory is free.
+
+### Before any external fetch
+1. Check `noor-recognition` for prior research on the same question
+2. Check coach-kernel ledger for prior decisions referencing this domain
+3. Check user memory (via `memory_search`) for owner statements on this topic
+4. ONLY fetch externally if memory is genuinely insufficient
+
+### When memory + new fetch combine
+- Lead with what we already know (cite memory)
+- Add what's new (cite fresh sources with dates)
+- Note where memory and fresh fetch disagree (surface the contradiction)
+
+## 8. Wide-Research Patterns (when ≥10 entities)
+
+For batch research:
+- ≤9 entities: individual `fetch_url` / `search_web` calls
+- 10-19 entities: `wide_research` or `wide_browse` (no confirmation gate)
+- 20+ entities: `confirm_action` first, then `wide_research`/`wide_browse`
+
+### Schema design for wide_research
+```typescript
+// Schema file passed to wide_research
+{
+  type: 'object',
+  properties: {
+    company_name: { type: 'string', title: 'Company' },
+    pricing_tier_1: { type: 'string', title: 'Starter Price' },
+    pricing_tier_2: { type: 'string', title: 'Pro Price' },
+    activation_signal: { type: 'string', title: 'Activation Signal' },
+    sources: { type: 'string', title: 'Sources' },  // markdown links
+  }
+}
+```
+
+Output: CSV with one row per entity. Use the CSV in subsequent synthesis.
+
+## 9. Source Citation Discipline
+
+### Inline citation format (per main doctrine)
+- ✅ "Linear charges $8/seat ([Linear pricing page](https://linear.app/pricing))"
+- ❌ "Linear charges $8/seat (source 1)"
+- ❌ "Linear charges $8/seat" (no citation)
+
+Anchor text MUST be the source name, never "source" / "link" / "click here". Every fact-claim has its citation.
+
+### Per-skill citation styles
+- **For owner-facing summary**: inline markdown links (above)
+- **For gate-block JSON**: structured sources array
+- **For artifact files (PDFs / docs)**: footnote with full URL + accessed-date
+- **For cookbook references**: prose URL inline ([source name](url))
+
+## 10. Anti-Patterns
+
+### Running research before checking memory (Noor)
+Wasted cost; slower turn. Memory first; fetch on gap.
+
+### Vague research requests not decomposed
+"Research X" returns vague answers. Decompose to 2-5 specific sub-questions.
+
+### Quoting tertiary as if primary
+A Reddit thread is signal, not evidence. Use tertiary for sentiment direction, not facts.
+
+### Single-sourcing time-sensitive claims without flagging
+Pricing on one vendor page is single-sourced. Mark it explicitly. Don't bury.
+
+### Burying conclusion in bibliography
+Lead with the answer. Sources support; they don't substitute.
+
+### Failing to hand synthesis back to calling skill
+Research is dead context if not consumed. Always synthesize back to the requester in their format.
+
+### Live-fetching when memory is sufficient
+Aria's garden + pulse + hive substrate already contains relevant prior research. Check before fetching.
+
+## 11. Research checklist (paste-ready)
+
+```markdown
+## Decomposition
+- [ ] Request decomposed into 2-5 specific sub-questions
+- [ ] Source class declared per sub-question (primary / secondary / tertiary)
+- [ ] Freshness window matched to question type
+- [ ] Success criterion named per sub-question
+
+## Memory-first
+- [ ] Noor checked for prior research
+- [ ] Coach-kernel ledger checked for prior decisions
+- [ ] User memory checked for owner statements
+
+## Fetching
+- [ ] Right tool per sub-question (fetch_url / search_web / vertical / browser_task / wide_*)
+- [ ] Queries written natural-phrase
+- [ ] Parallel where independent
+
+## Verification
+- [ ] Each non-trivial claim cross-verified OR flagged single-sourced
+- [ ] Freshness check passed; stale sources noted
+- [ ] Source-class hierarchy respected (primary > secondary > tertiary)
+
+## Synthesis
+- [ ] Conclusion leads (headline first per readable-output)
+- [ ] Sub-questions answered with citation each
+- [ ] Caveats flagged (single-sourced, partial freshness, contradictions)
+- [ ] Synthesis handed back to calling skill in calling-skill-native format
+
+## Coach kernel
+- [ ] Research event recorded with `risk_class: 'research_action'`
+- [ ] Freshness + source-quality predicate recorded
+- [ ] Recovery contract gateType: advisory (research is teach-not-block)
+```

package/skills/aria-cognition/aria-retention-engine/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: aria-retention-engine
+description: TRIGGER for any churn, retention, renewal, expansion, NPS, CSAT, onboarding, activation, escalation, refund-save, win-back, account-health, customer-success, or post-sale lifecycle decision. Composes the cognitive substrate with a churn-cause + retention-leverage + cohort-decay frame.
+---
+
+# Aria Retention Engine
+
+Cognition skill for the post-sale lifecycle. Most net revenue retention dies in the first 30 days; most expansion is invisible until you measure it cohort-by-cohort. This skill exists to make those signals visible before the renewal call.
+
+## Prime Doctrine
+
+Retention is upstream of every other metric. A 90% NRR business at any growth rate is in trouble; a 130% NRR business at any growth rate is compounding. Optimize retention before optimizing acquisition.
+
+- **Churn is rarely about price.** It's about expected vs delivered value, friction, and life-cycle moments. Pricing as a churn explanation is usually a stand-in for a deeper truth.
+- **The first 7 days set the next 12 months.** Activation depth in week 1 predicts month-12 retention more than any single feature.
+- **Renewals are won 90 days before the renewal date.** A renewal won in the renewal week is a coin flip; one won in the prior quarter is structural.
+- **Expansion is the silent revenue lever.** A 110% gross retention business with 130% net retention has 2× the LTV of a 110% gross / 110% net business at the same cost.
+
+## Trigger Detection
+
+Fire on:
+
+- Churn analysis / churn-cause investigation
+- Renewal forecast / renewal at-risk identification
+- Expansion / upsell / cross-sell strategy (post-sale)
+- NPS / CSAT / health-score design or interpretation
+- Onboarding / activation flow design
+- Customer escalation / refund-save / make-good
+- Win-back campaign for churned cohort
+- Account-health scoring or QBR design
+
+## Required Workflow (cause-leverage-decay)
+
+Every retention decision must answer:
+
+1. **Churn-cause decomposition.** Split current churn into: (a) wrong-fit (should have been disqualified at sale), (b) un-activated (signed but never adopted), (c) life-cycle (changed jobs, sunset use case), (d) competitor-loss (real comparison loss), (e) price (validated, not assumed). Each has a different fix.
+2. **Retention-leverage map.** For the dominant churn cause, what is the highest-leverage intervention? Onboarding redesign helps cause (b) but does nothing for (a). Sales qualification changes help (a) but don't help (b).
+3. **Cohort-decay curve.** Plot survival by cohort (acquisition month). Is the curve flattening (good — fixes are landing), steepening (bad — recent cohorts are worse), or unchanged (no signal yet)?
+
+## Retention-Mapped Lenses
+
+`ghazali-8lens` under retention:
+
+- **truth** — is the churn data complete? Are paused / downgraded / silent-departed customers counted?
+- **harm** — does the retention intervention create resentment (e.g., aggressive save calls)?
+- **trust** — does the win-back offer respect the original commitment, or feel manipulative?
+- **power** — is the customer locked-in by data export friction, or genuinely choosing to stay?
+- **reflection** — would the saved customer recommend us 6 months later, or is this a save that becomes a detractor?
+- **context** — is this churn driven by something external (industry shift) or internal (product gap)?
+- **impact** — NRR / GRR delta at the cohort level, with confidence
+- **beauty** — does the renewal experience feel earned, or transactional?
+
+## User-Facing Layout
+
+```
+## [Decision: name the churn cause + leverage point + intervention in one line]
+
+- [Cohort decomposition — split by month or segment, real numbers]
+- [Dominant churn cause — named with evidence]
+- [Highest-leverage intervention — concrete, scoped]
+- [Predictor predicate — NRR / GRR / activation rate target]
+
+**Next:** [first concrete action with measurable check at 30/60/90 days]
+```
+
+## Composition Rule
+
+- Composes with `aria-business-frame`
+- Calls `aria-customer-truth` for churn-reason interviews (the only reliable source for cause attribution)
+- Calls `aria-revenue-engine` if the churn cause genuinely is price (rare but real)
+- Calls `mizan`, `tadabbur`, `ghazali-8lens` per business-frame defaults
+- Calls `predictor` for the cohort-survival predicate
+- Calls `noor-recognition` for prior retention experiments and their actual cohort impact
+
+## Recovery Contract
+
+- If churn-cause data is missing: do NOT recommend an intervention. Recommend a 10-customer churn-interview sprint via `aria-customer-truth`, or surface 3 hypotheses with explicit confidence weights.
+- If the cohort sample is too small (< 30 churned in the relevant cohort): say so explicitly. "We don't have enough cohort data to recommend a structural change; here's a non-structural pilot."
+- If the retention intervention will burn customer trust (e.g., aggressive save calls, dark-pattern downgrade flows): hard NO via `ghazali-8lens` trust lens. Surface alternatives.
+- Log retention decisions to coach kernel with `risk_class: 'retention_action'` and the cohort-survival predicate.
+
+## Anti-Patterns
+
+- Treating overall churn rate as if it were homogeneous (always decompose by cohort + cause)
+- Recommending feature work as a churn fix when the dominant cause is wrong-fit at sale
+- Aggressive saves that win the dollar and lose the referral
+- Win-back campaigns to churned customers without fixing the original churn cause
+- NPS as a churn predictor (it's noisier than usage data; use both, not just NPS)
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.
+
+
+## Self-Executing Recovery Contract
+
+If retention recommendation cannot be made:
+
+- One re-run with the missing decomposition or interview evidence
+- If still insufficient, recommend the smallest cohort-isolated test (e.g., A/B activation flow on the next 50 signups) with stop-criteria
+- Never present a retention recommendation as confident without cohort evidence supporting it
+
+## Why This Exists
+
+Most owners over-invest in acquisition and under-invest in retention because retention is harder to measure and slower to compound. This skill makes the cognition explicit so the lever doesn't get ignored.

package/skills/aria-cognition/aria-retention-engine/references/retention-cookbook.md

@@ -0,0 +1,271 @@
+# Retention Engine Cookbook — Churn, Onboarding, Expansion Patterns
+
+> Loaded by `aria-retention-engine` for churn analysis, renewal forecasting, expansion strategy, escalation handling.
+> See also: [`../../aria-business-frame/references/business-cookbook.md`](../../aria-business-frame/references/business-cookbook.md) (constraint categories, NRR benchmarks)
+> See also: [`../../aria-revenue-engine/references/revenue-cookbook.md`](../../aria-revenue-engine/references/revenue-cookbook.md) (NRR/GRR math, cohort patterns)
+
+## 1. The 5 Churn Causes (decompose before intervening)
+
+Most churn analyses are wrong because they assume churn is one thing. It's five.
+
+### 1. Wrong-fit at sale
+- Customer signed up for the wrong reason; never had a real fit
+- **Signal**: short-tenure churn (months 1-3); cohort-decomposed by acquisition channel often shows one channel concentrating wrong-fit
+- **Fix**: sales qualification criteria; ICP definition tightening; channel mix adjustment
+- **Wrong fix**: onboarding redesign (won't help — they never had a problem to solve here)
+
+### 2. Un-activated
+- Signed up but never reached the aha moment
+- **Signal**: usage data shows no key actions in first 7-14 days; logins drop after week 2
+- **Fix**: onboarding redesign; activation moment redefinition; in-product nudges
+- **Wrong fix**: more emails (the unactivated cohort isn't reading)
+
+### 3. Life-cycle
+- Their use case sunset; they changed roles; their company got acquired
+- **Signal**: long-tenure churn (year 2+); usage was healthy until end
+- **Fix**: adjacent product expansion; champion-departure-triggered playbooks; accept some as natural
+- **Wrong fix**: pricing changes (the price isn't the problem)
+
+### 4. Competitor-loss
+- Real comparison loss to another vendor
+- **Signal**: explicit competitor mentioned in churn interview; usage steady until cancel
+- **Fix**: feature gap closure; positioning sharpening; pricing recalibration
+- **Wrong fix**: discount-to-save (you're buying churn — the relationship is already lost)
+
+### 5. Price (validated, not assumed)
+- Genuinely a budget issue; would have stayed at lower price
+- **Signal**: explicit budget cite; downgrade attempt before churn
+- **Fix**: lower-priced tier; usage-based component; annual prepay discount
+- **Wrong fix**: discount the existing price (creates discount cohort drag — see revenue cookbook §3)
+
+### The diagnostic
+Each cause needs a different fix. Misdiagnosis is the most common retention-engine failure. Decompose churn into cause categories BEFORE recommending intervention.
+
+## 2. Cohort-decay curves (replace flat churn for runway)
+
+**Source:** [Fiscallion — SaaS Cohort Analysis](https://www.fiscallion.io/blog/saas-cohort-analysis-how-to-turn-retention-data-into-decisions)
+
+### The pattern
+Most SaaS lose more customers in months 1-3 than 9-12. A flat churn assumption:
+- Overstates near-term revenue (churn is higher early than the average)
+- Understates long-term retention (survivors are stickier than the average)
+
+### The fix
+Replace flat churn with cohort decay curves for runway forecasts:
+- Compute survival % at month 1, 3, 6, 12, 18, 24 for each acquisition cohort
+- Fit a power-law or Weibull decay curve
+- Project forward; compare to flat-churn projection
+- Differential is real revenue — often the difference between "raise now" and "extend runway"
+
+### Reference SQL (cohort survival)
+```sql
+WITH cohort_signups AS (
+  SELECT customer_id, DATE_TRUNC('month', signup_date) as cohort_month
+  FROM customers
+),
+cohort_survival AS (
+  SELECT
+    cs.cohort_month,
+    DATE_TRUNC('month', s.subscription_active_date) as period_month,
+    COUNT(DISTINCT s.customer_id) as active_customers,
+    DATEDIFF('month', cs.cohort_month, DATE_TRUNC('month', s.subscription_active_date)) as months_since_signup
+  FROM cohort_signups cs
+  JOIN subscriptions s ON s.customer_id = cs.customer_id
+  GROUP BY 1, 2
+),
+cohort_size AS (
+  SELECT cohort_month, COUNT(DISTINCT customer_id) as initial_size
+  FROM cohort_signups
+  GROUP BY 1
+)
+SELECT
+  cs.cohort_month,
+  cs.months_since_signup,
+  cs.active_customers,
+  cz.initial_size,
+  cs.active_customers::float / cz.initial_size as survival_rate
+FROM cohort_survival cs
+JOIN cohort_size cz USING (cohort_month)
+ORDER BY cs.cohort_month, cs.months_since_signup;
+```
+
+## 3. PLG Onboarding Pattern — activation as the leading indicator
+
+**Source:** [Lumi Studio — PLG Onboarding](https://www.lumi.studio/blog/a-guide-to-plg-onboarding) · [productled.org](https://www.productled.org/foundations/product-led-growth-metrics)
+
+### Activation rate benchmarks
+- **20-40% = OK** (depending on onboarding complexity)
+- **>50% = excellent**
+- Activation = % of signups who reach the aha moment (first valuable action)
+
+### Day-7 retention is the leading indicator
+- Do users who hit the aha moment come back?
+- Day-7 retention is more predictive of month-12 retention than any single feature
+- If aha-moment users don't return, the aha moment isn't actually valuable — it's a proxy metric
+
+### The PLG funnel (defining each stage by behavior, not assumption)
+
+| Stage | Definition | Benchmark |
+|---|---|---|
+| Stranger | Hasn't found us | — |
+| Explorer | Visited landing | Website→signup 6-9% (freemium), 3-4% (trial) |
+| Beginner | Signed up | — |
+| Activated | Hit aha moment | 20-40% of signups |
+| Regular | Habitual use | 60%+ of activated users by day 30 |
+| Champion | Refers others | NPS ≥ 50 + 1+ referral |
+
+### The activation playbook
+1. **Define the aha moment behaviorally** — single action, measurable, time-bounded
+2. **Measure baseline activation** for last 90-day cohort
+3. **Identify drop-off points** before the aha moment (each is a fix candidate)
+4. **Design ONE intervention** at the highest-drop step; A/B test
+5. **Measure activation lift + day-7 retention lift** (both, not just activation)
+6. **Iterate**
+
+### Common aha-moment definitions
+- Slack: 2,000 messages sent in a workspace
+- Dropbox: 1 file uploaded + 1 device installed
+- Hubspot: First contact imported + first email sent
+- Stripe: First successful charge processed
+
+## 4. PQL (Product Qualified Lead) — the PLG sales-handoff signal
+
+### Three PQL metrics
+1. **PQL count** over time
+2. **PQL rate** (% of signups becoming PQL)
+3. **PQL-to-paid conversion**
+
+### PQL trigger criteria
+- Feature adoption thresholds (e.g., used feature X ≥ 5 times)
+- Usage caps approached (signals expansion need)
+- Team expansion (multiple seats activated)
+- Use-case depth signals (configured key integrations)
+
+### When to hand off to sales
+- PQL with team-expansion signal (multi-seat product) → expansion-focused outreach
+- PQL approaching usage cap (usage-based pricing) → upgrade-focused outreach
+- Free-tier user with enterprise-shaped usage pattern (compliance, audit needs) → upmarket-conversion outreach
+
+## 5. NPS / CSAT / Health Score (signal weights)
+
+### NPS (Net Promoter Score) — limited as churn predictor
+- Asks "how likely to recommend, 0-10"
+- Promoters (9-10) − Detractors (0-6) = NPS (range -100 to 100)
+- **NPS is noisier than usage data** — use both, not just NPS
+- Useful for: brand health, expansion potential
+- Less useful for: churn prediction (a 9 today churns next month if usage drops)
+
+### CSAT (Customer Satisfaction)
+- Specific to interactions ("how satisfied with this support response, 1-5")
+- Better signal than NPS for operational quality
+
+### Health Score (composite)
+The right model: weighted combination of:
+- **Product usage** (depth, breadth, frequency) — 40% weight
+- **Engagement** (logins, sessions, time-on-task) — 20% weight
+- **Outcome metrics** (customer's KPI achievement, where measurable) — 20% weight
+- **Survey signal** (NPS, CSAT, support sentiment) — 10% weight
+- **Account context** (champion changes, executive sponsor, contract status) — 10% weight
+
+### Health score thresholds
+- **Green** (≥70) — expansion candidate
+- **Yellow** (40-69) — standard cadence; monitor
+- **Red** (<40) — escalate; CSM intervention; pre-renewal preparation
+- **Auto-escalate** triggers: champion departure, usage drop >50% in 30 days, support escalation pattern
+
+## 6. Renewal cycle (90-day window pattern)
+
+### The discipline
+**Renewals are won 90 days BEFORE the renewal date.** A renewal won in the renewal week is a coin flip; one won in the prior quarter is structural.
+
+### 90-day pre-renewal playbook
+- **T-90**: account review with CSM + AE; map champion + decision-maker; verify health score; identify expansion vector
+- **T-60**: explicit value-recap with the champion; quantify outcomes; introduce expansion conversation if green
+- **T-30**: contract redline conversation with decision-maker; pricing locked or escalation defined
+- **T-14**: signature on renewal + expansion (if applicable)
+- **T-0**: renewal lands; QBR scheduled for post-renewal
+
+### Anti-patterns
+- Starting renewal conversation in the renewal week (signals scramble)
+- Discount-to-save (you're buying churn; structurally the relationship is already lost)
+- Multi-stakeholder mismatch (champion sold us; finance kills us at renewal because never met them)
+- Auto-renewal without explicit conversation (signals you're not paying attention; gives competitors entry)
+
+## 7. Expansion / upsell / cross-sell (the silent revenue lever)
+
+### Expansion shapes
+- **Seat expansion** — same product, more users
+- **Tier upgrade** — same users, more features (Pro → Enterprise)
+- **Module / cross-sell** — adjacent product (Sales Cloud → Service Cloud)
+- **Usage growth** — usage-based pricing tier crossing
+
+### The math
+A 110% gross retention business with 130% net retention has **2× the LTV** of a 110% gross / 110% net business at the same cost.
+
+### Expansion playbook
+1. **Identify expansion vector per cohort** — what does each ICP segment expand into?
+2. **Trigger criteria** — usage-cap approach, team growth, champion promotion, integration adoption
+3. **Pricing design** — make the expansion path visible in the product (paywall hints, lock icons, "request access")
+4. **CSM compensation** — % of NRR > 100% = healthy comp design; flat $ on save = wrong incentive
+
+### When NOT to push expansion
+- Health score < 40 (you'll burn the relationship)
+- Champion departed in last 30 days (rebuild trust first)
+- Active escalation open (don't compound friction)
+- Customer hasn't reached aha moment in current tier (premature)
+
+## 8. Win-back campaigns (only fix the cause first)
+
+### The win-back paradox
+Win-back campaigns that don't fix the original churn cause produce churn-back — they re-acquire the same wrong-fit customer who churns again at higher cost.
+
+### The win-back checklist
+```markdown
+- [ ] Original churn cause identified per §1 (wrong-fit / un-activated / life-cycle / competitor / price)
+- [ ] Original cause fixed in product / pricing / onboarding (verified by current-cohort data)
+- [ ] Time elapsed since churn ≥ 6 months (cooling-off)
+- [ ] Customer was healthy before they churned (don't win-back wrong-fit)
+- [ ] Win-back offer is value-based (new feature, new pricing tier, new use case) — NOT just discount
+- [ ] Predictor: win-back cohort retention ≥ original cohort retention at same tenure
+```
+
+### Anti-patterns
+- "We miss you" emails with discount — wrong-fit customers re-churn
+- Win-back to churned competitor-loss customers without addressing why they left
+- Bulk win-back to all churned (segment by cause first)
+
+## 9. Escalation handling (turn detractors into advocates)
+
+### The Sweet&Sour pattern (Reflexion-style for retention)
+
+When a customer escalates:
+1. **Sour first** — acknowledge the specific failure: "X happened, Y was the cost to you, here's what went wrong on our side"
+2. **Investigate fully** — root cause; not just the symptom
+3. **Make it right disproportionately** — refund + future credit + named owner of fix + commitment to update them
+4. **Sweet** — once resolved, follow up to verify resolution + invite them to be a reference
+
+### The data
+A customer whose escalation is handled well becomes more loyal than one who never had an issue (the "service recovery paradox"). But only if handled well — half-handled escalations create permanent detractors.
+
+### Anti-patterns
+- Defensive responses that explain why we did the right thing
+- Half-refunds that signal "we're admitting partial fault"
+- Generic "thank you for your feedback" with no concrete fix
+- No follow-up after resolution
+
+## 10. Retention audit checklist (paste-ready)
+
+```markdown
+- [ ] Churn decomposed by cause (not lumped as one number)
+- [ ] Cohort decay curves computed (not flat churn assumption)
+- [ ] NRR + GRR computed at cohort level
+- [ ] Activation rate measured + benchmarked (20-40% OK, 50%+ excellent)
+- [ ] Day-7 retention measured for activated cohort
+- [ ] Health score model defined; green/yellow/red thresholds
+- [ ] Pre-renewal playbook in place (T-90, T-60, T-30, T-14)
+- [ ] Expansion vector identified per ICP segment
+- [ ] CSM compensation aligned to NRR > 100% (not flat $)
+- [ ] Win-back conditions defined (cause fixed + cooling-off + value offer)
+- [ ] Coach-kernel write with `risk_class: 'retention_action'` + cohort predicate
+- [ ] Recovery contract gateType: advisory (recovery, not block)
+```