rsc-universal 0.1.1

package/skills/kotlin-android/scripts/verify.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# verify.sh — static, SDK-free lint for native Android (Kotlin + Gradle).
+#
+# Greps the target dir for stale/banned Android patterns and missing modern ones.
+# No Android SDK, no Gradle, no network required — runs in CI or a bare checkout.
+#
+#   bash scripts/verify.sh [DIR]   # DIR defaults to the current directory
+#
+# FAIL (exit 1): a banned pattern is present.
+# WARN (exit 0): a modern pattern looks missing — review, don't necessarily block.
+# An empty or clean target exits 0 with "all checks passed".
+#
+# Portable to stock macOS bash 3.2 (no mapfile, no associative arrays).
+set -eu
+
+DIR="${1:-.}"
+
+RED=$'\033[0;31m'
+YELLOW=$'\033[1;33m'
+GREEN=$'\033[0;32m'
+RESET=$'\033[0m'
+
+fails=0
+warns=0
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$1"; fails=$((fails + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$RESET" "$1"; warns=$((warns + 1)); }
+
+if [ ! -d "$DIR" ]; then
+  warn "target '$DIR' is not a directory — nothing to check"
+  exit 0
+fi
+
+# Collect target files. Exclude build output and this skill's own references.
+kt_files=$(find "$DIR" -type f -name '*.kt' \
+  -not -path '*/build/*' -not -path '*/.gradle/*' 2>/dev/null || true)
+gradle_files=$(find "$DIR" -type f -name '*.gradle.kts' \
+  -not -path '*/build/*' 2>/dev/null || true)
+xml_layouts=$(find "$DIR" -type f -path '*/res/layout/*.xml' \
+  -not -path '*/build/*' 2>/dev/null || true)
+
+if [ -z "$kt_files" ] && [ -z "$gradle_files" ] && [ -z "$xml_layouts" ]; then
+  printf '%sno Kotlin/Gradle/layout files under %s — nothing to check.%s\n' "$GREEN" "$DIR" "$RESET"
+  exit 0
+fi
+
+# grep helper: returns 0 (and prints) when PATTERN is found in $kt_files.
+kt_grep() { [ -n "$kt_files" ] && printf '%s\n' "$kt_files" | xargs grep -nE "$1" 2>/dev/null; }
+gradle_grep() { [ -n "$gradle_files" ] && printf '%s\n' "$gradle_files" | xargs grep -nE "$1" 2>/dev/null; }
+
+# ---- FAIL checks: banned patterns -----------------------------------------
+[ -n "$xml_layouts" ] && fail "XML layout files under res/layout — use Jetpack Compose:
+$(printf '%s\n' "$xml_layouts" | sed 's/^/    /')"
+
+hit=$(kt_grep '\bfindViewById\b') && [ -n "$hit" ] && \
+  fail "findViewById (no Compose):"$'\n'"$(printf '%s' "$hit" | sed 's/^/    /')"
+
+hit=$(kt_grep '\bAsyncTask\b') && [ -n "$hit" ] && \
+  fail "AsyncTask (removed API) — use coroutines:"$'\n'"$(printf '%s' "$hit" | sed 's/^/    /')"
+
+hit=$(kt_grep 'GlobalScope\.(launch|async)') && [ -n "$hit" ] && \
+  fail "GlobalScope coroutine (leaks) — use viewModelScope/a scoped CoroutineScope:"$'\n'"$(printf '%s' "$hit" | sed 's/^/    /')"
+
+hit=$(kt_grep 'import +androidx\.lifecycle\.LiveData') && [ -n "$hit" ] && \
+  fail "LiveData import — use StateFlow + collectAsStateWithLifecycle():"$'\n'"$(printf '%s' "$hit" | sed 's/^/    /')"
+
+hit=$(gradle_grep '\bkapt\b') && [ -n "$hit" ] && \
+  fail "kapt in Gradle (legacy/slow) — use KSP for Room/Hilt:"$'\n'"$(printf '%s' "$hit" | sed 's/^/    /')"
+
+# Public mutable state surface: a 'val' exposing MutableStateFlow/mutableStateOf
+# without a 'private' modifier is a leaked source of truth.
+hit=$(kt_grep '^[[:space:]]*(public[[:space:]]+)?val[[:space:]].*(MutableStateFlow|mutableStateOf)\(') \
+  && [ -n "$hit" ] && \
+  fail "public val exposing MutableStateFlow/mutableStateOf — keep mutable private, expose StateFlow via asStateFlow():"$'\n'"$(printf '%s' "$hit" | sed 's/^/    /')"
+
+# ---- WARN checks: missing modern patterns ----------------------------------
+# collectAsState( without the Lifecycle variant in the same set of files.
+if [ -n "$kt_files" ]; then
+  plain=$(printf '%s\n' "$kt_files" | xargs grep -lE 'collectAsState\(' 2>/dev/null || true)
+  lifecycle=$(printf '%s\n' "$kt_files" | xargs grep -lE 'collectAsStateWithLifecycle\(' 2>/dev/null || true)
+  # Files that use collectAsState but never the lifecycle variant.
+  for f in $plain; do
+    case " $lifecycle " in
+      *" $f "*) : ;;
+      *) warn "collectAsState() without collectAsStateWithLifecycle() in: $f" ;;
+    esac
+  done
+fi
+
+hit=$(gradle_grep 'composeOptions[[:space:]]*\{') && [ -n "$hit" ] && \
+  warn "legacy composeOptions block — use the Kotlin Compose plugin (org.jetbrains.kotlin.plugin.compose):"$'\n'"$(printf '%s' "$hit" | sed 's/^/    /')"
+
+if [ -n "$gradle_files" ]; then
+  if ! printf '%s\n' "$gradle_files" | xargs grep -qE 'compose-bom|platform\(.*compose' 2>/dev/null; then
+    warn "no compose-bom platform() pin found in Gradle — pin Compose artifacts via the BOM."
+  fi
+fi
+
+# ---- summary ---------------------------------------------------------------
+printf -- '----\n'
+if [ "$fails" -gt 0 ]; then
+  printf '%s%d failure(s)%s, %d warning(s).\n' "$RED" "$fails" "$RESET" "$warns"
+  exit 1
+fi
+if [ "$warns" -gt 0 ]; then
+  printf '%s%d warning(s)%s, no failures.%s\n' "$YELLOW" "$warns" "$RESET" "$RESET"
+  exit 0
+fi
+printf '%sall checks passed.%s\n' "$GREEN" "$RESET"
+exit 0

package/skills/kpi-framework/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: kpi-framework
+description: "Use when a team must decide what to measure before building anything — picking one north-star metric, separating leading input drivers from lagging outputs, adding guardrails so a number can't be gamed, or setting a target that isn't arbitrary. Triggers: 'what should we even be measuring', 'we track 40 KPIs and nothing leads anywhere', 'is signups a leading or lagging indicator', 'set an activation target that won't get gamed', 'pick a north star for the product', 'audit our vanity metrics', 'quins KPIs triem per al producte', 'qué métrica norte elegimos'. NOT building the live dashboard that displays them (that is dashboard), NOT instrumenting the events (that is analytics), NOT the recurring board report (that is reporting)."
+tags: [north-star-metric, leading-vs-lagging, input-metrics, guardrail-metrics, target-setting, vanity-metrics, kpi-tree]
+recommends: [analytics, dashboard, reporting, ab-testing, forecasting, business-intelligence, unit-economics, project-ops]
+origin: risco
+---
+
+# KPI framework
+
+You decide **what** to measure. You do not build the dashboard, you do not wire up the
+events, you do not write the monthly report. Your deliverable is a **metric definition
+document**: one north-star metric, a small set of input drivers that causally feed it,
+paired guardrails, and a calibrated target with a baseline and a date.
+
+Most measurement work fails upstream, before any chart exists. Teams instrument 40 KPIs
+and none of them lead anywhere. They optimize a lagging output nobody can move. They
+celebrate a vanity number. They set "double it this month" and watch it get gamed. Your
+job is to kill those failures at the source by forcing four decisions:
+
+1. **What single output predicts long-term value?** (the north star)
+2. **Which 3-5 controllable inputs cause it?** (the driver set)
+3. **What breaks if we over-optimize it?** (the guardrails)
+4. **What target — baseline, magnitude, date — is honest and ungameable?**
+
+Answer those four and hand the result to `../analytics/SKILL.md` to instrument and
+`../dashboard/SKILL.md` to display. If you find yourself choosing chart types or writing
+SQL, you have left this skill.
+
+## The one artifact
+
+Everything you produce collapses into a single table. Nothing leaves this skill with the
+baseline, target, or date column blank — an unfilled target is a decision you skipped, not
+a decision you made.
+
+| metric | type | definition (event + window + denominator) | leading/lagging | owner | baseline | target | target_date |
+|---|---|---|---|---|---|---|---|
+| Weekly Active Teams | north-star | teams with >=1 member completing a core action in a rolling 7-day window / all active teams | lagging | PM, Activation | 38% | 52% | 2026-Q4 |
+| Time-to-first-core-action | input | median minutes from signup to first core action, new teams | leading | PM, Onboarding | 41 min | <15 min | 2026-Q3 |
+| Week-1 saved items | input | new teams with >=3 saved items in first 7 days / new teams | leading | PM, Onboarding | 22% | 40% | 2026-Q3 |
+| Invites accepted | input | invited members who activate within 7 days / invites sent | leading | Growth | 31% | 45% | 2026-Q4 |
+| Support tickets / active team | guardrail | open tickets / weekly active teams (must not rise) | lagging | Support lead | 0.12 | <=0.12 | ongoing |
+
+The columns are not decoration. "Definition" must be unambiguous enough that two analysts
+querying independently get the same number — that means a concrete **event**, a **time
+window**, and a **denominator**. See `references/definition-and-targets.md` for how to
+write definitions that don't drift.
+
+## Step 1 — Pick ONE north star (the output)
+
+**The north star is an output / lagging metric.** Why: it's the scoreboard for value
+delivered, deliberately too broad to act on directly. You don't push the north star — you
+push the inputs and watch the north star move. One per team; more than one means no team
+actually owns the outcome.
+
+**Express delivered value as a rate or ratio, not a raw count.** Why: raw counts grow with
+time and headcount and hide health — "total users" goes up even as the product dies.
+
+- Bad: `total registered users`
+- Good: `weekly active teams that completed a core action / all active teams`
+
+**It must predict long-term retention or revenue.** If the number can climb for a quarter
+while the business erodes, it is not a north star. The test: would you bet next year's
+retention on this number rising? If not, keep looking.
+
+**Vanity reject test.** Followers, page views, likes, total signups — vanity unless tied to
+a downstream outcome (conversion, revenue, retention). 10k followers with zero sales lift
+is the canonical example. If a candidate metric can double with no change in value
+delivered, reject it and say why in the doc.
+
+Source candidates from a lens — AARRR (acquisition/activation/retention/referral/revenue)
+or HEART (happiness/engagement/adoption/retention/task-success) — then narrow to one.
+`references/metric-catalog.md` lists candidate north stars and driver sets per business
+type (SaaS, marketplace, content, e-commerce, B2B sales-led).
+
+## Step 2 — Build the driver set (3-5 inputs)
+
+The north star is the scoreboard; the inputs are the plays you actually run.
+
+**Each input is leading, directly controllable, and a concrete instrumentable event.** Why:
+if the team can't influence it through their own work, it's not an input — it's another
+output, and chasing it is vanity. "Engagement" and "satisfaction" are not inputs; they're
+abstractions you cannot ship against.
+
+- Bad: `increase engagement`
+- Good: `% of new teams with >=1 saved item in the first 7 days`
+
+**Each input must plausibly *cause* the north star.** Why: a metric tree connects every
+node to its parent (the outcome) and its children (the inputs). A standalone number has no
+defense against gaming; in a tree, gaming one node shows up as distortion in its neighbors.
+Draw the tree so the causal claim is explicit and falsifiable:
+
+```text
+        Weekly Active Teams (north star, output)
+        /              |                 \
+Time-to-first      Week-1 saved        Invites accepted
+core action        items (>=3)         within 7 days
+(leading)          (leading)           (leading)
+```
+
+**Cap the set at 5.** Why: more than five inputs is sprawl — focus dilutes, nobody owns the
+list, and you're back to the 40-KPI swamp you came to escape. If you have eight candidates,
+the work of this step is cutting three.
+
+Hand the final event list — exact events, windows, denominators — to `../analytics/SKILL.md`
+to instrument. You define them; analytics implements them.
+
+## Step 3 — Add guardrails / countermetrics
+
+> "When a measure becomes a target, it ceases to be a good measure." — Goodhart's Law (Charles Goodhart, 1975)
+
+Single-metric optimization gets gamed. Optimize sales volume alone and reps discount to the
+floor; optimize Average Handle Time alone and agents hang up on unsolved problems.
+
+**Every target gets a paired shadow metric representing the foreseeable harm.** Why: the
+guardrail is what catches the gaming before it costs you. The pair must measure the thing
+that breaks when someone over-optimizes the target.
+
+| north-star / target you push | likely gaming move | guardrail to pair |
+|---|---|---|
+| Average Handle Time ↓ | agents close tickets prematurely | First Contact Resolution + Customer Effort Score |
+| Activation rate ↑ | loosen "activated" definition, count trivial actions | week-4 retention of newly-activated cohort |
+| Signups ↑ | buy low-intent traffic | activation rate of new signups |
+| Revenue per order ↑ | aggressive upsell, hidden fees | refund rate + repeat-purchase rate |
+| Sessions per user ↑ | dark patterns, notification spam | uninstall / unsubscribe rate |
+
+A guardrail does not need a stretch target — its target is usually "must not get worse than
+baseline." Write it into the table anyway, with `ongoing` as the date.
+
+## Step 4 — Set the target
+
+This is where frameworks most often break: arbitrary numbers that discourage, or
+sandbagged ones that drive nothing.
+
+**Baseline before target.** Why: you cannot calibrate a target without knowing current
+state. "Get to 50%" is meaningless until you know whether you're at 12% or 48%. If there is
+no baseline, the first deliverable is "measure the baseline" — do not invent a target on
+top of an unknown.
+
+**Magnitude must be calibrated — not arbitrary, not sandbagged.** Why: targets that are too
+ambitious hurt performance through burnout and shortcuts; targets that are trivially safe
+drive no improvement. Ground the magnitude in the baseline (a defensible improvement band)
+and the levers you actually have, not in a round number that sounds good in a deck.
+
+- Bad: `double activation this month`
+- Good: `activation 38% → 52% by 2026-Q4, owner: PM Activation, based on onboarding rework + invite flow`
+
+**Attach a date and an owner to every target.** Why: a target with no date is a wish; a
+target with no owner is nobody's job. A row missing either is incomplete.
+
+See `references/definition-and-targets.md` for baseline measurement, improvement-band
+calibration, and why round-number targets invite theatre.
+
+## Decision table — is this row a north star, an input, a guardrail, or noise?
+
+| the metric is... | controllable by the team? | tied to delivered value? | → classify as |
+|---|---|---|---|
+| an output (outcome) | no (you steer it via inputs) | yes, predicts retention/revenue | **north star** (pick one) |
+| an output | partially | yes, but could regress when pushing the NSM | **guardrail** |
+| an input (a play) | yes, directly | causally feeds the north star | **input driver** |
+| a count or output | no | no downstream outcome | **noise / vanity — reject** |
+
+If a candidate is controllable but doesn't feed the north star, it's a distraction. If it's
+tied to value but uncontrollable, it's either the north star itself or a guardrail. If it's
+neither controllable nor value-tied, cut it.
+
+## Anti-patterns
+
+| anti-pattern | why it bites | the fix |
+|---|---|---|
+| Vanity metric | grows without value moving; celebrates nothing real | tie to a downstream outcome or reject |
+| 40-KPI sprawl | nothing leads, no focus, no owner | one north star + 3-5 inputs, cut the rest |
+| Lagging-only | you can watch it but can't act on it | add controllable leading inputs |
+| Un-actionable input | team can't influence it through their work | replace with a concrete shippable event |
+| Arbitrary target | "double it" discourages or invites gaming | baseline first, then a calibrated band |
+| Single number, no guardrail | gets gamed, breaks a neighbor silently | pair every target with a countermetric |
+| Raw count as north star | rises with time/size, hides decline | use a rate or ratio tied to value |
+| Never re-validated | metric stops predicting value, nobody notices | re-check predictiveness semi-annually |
+
+## Re-validation cadence
+
+Re-validate the north star's **predictiveness** (does it still track retention/revenue?) and
+the inputs' **controllability** (can the team still move them?) at least **semi-annually**.
+Products and portfolios change; a metric that predicted value last year can quietly stop.
+Evolve definitions transparently — version the doc, note what changed and why, so a metric
+shift never looks like cooking the numbers.
+
+## Handoff
+
+When the metric definition doc is complete, route the downstream work:
+
+- Events to instrument (the exact inputs + windows) → `../analytics/SKILL.md`
+- What to display and how → `../dashboard/SKILL.md`
+- Recurring narrative around the numbers → `../reporting/SKILL.md`
+- Designing a test to move a specific input → `../ab-testing/SKILL.md`
+- Projecting a metric forward in time → `../forecasting/SKILL.md`
+- Cash/revenue economics, CAC/LTV behind the metric → `../unit-economics/SKILL.md`
+- Wiring KRs into an operating cadence → `../project-ops/SKILL.md`
+- Standing analytics models behind it all → `../business-intelligence/SKILL.md`

package/skills/kpi-framework/evals/README.md

@@ -0,0 +1,11 @@
+# Evals — kpi-framework
+
+These are LLM-graded prompts, not an automated test suite; no scorer ships with the skill.
+Run them through the repo's eval harness, or paste each prompt into a fresh agent with this
+skill available. For `should_trigger`, confirm the agent loads `kpi-framework`; for
+`should_not_trigger`, confirm it routes to the named sibling skill instead of loading this
+one. For the `capability` case, run the scenario and read the produced metric definition doc
+against every `must_include` bullet — a pass hits all of them (one rate-based north star,
+3-5 concrete leading inputs, a named guardrail, a baselined target with date + owner, an
+explicit vanity-metric rejection, and the analytics/dashboard handoff). Grading is by
+inspection against that rubric.

package/skills/kpi-framework/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: kpi-framework
+
+should_trigger:
+  - prompt: "What should we even be measuring for our new product?"
+    why: No agreed metric exists yet — the core 'choose what to measure' trigger.
+  - prompt: "We track 40 KPIs and none of them lead anywhere — help us pick what actually matters."
+    why: KPI sprawl with no leading metric; needs one north star plus a driver set. Non-obvious framing — the symptom is too many metrics, not too few.
+  - prompt: "Is 'signups' a leading or lagging indicator for us?"
+    why: Leading-vs-lagging classification of an output metric, the input/output distinction at the heart of the skill.
+  - prompt: "Set an activation-rate target that won't get gamed."
+    why: Non-obvious — pairs target-setting with Goodhart's Law and guardrail design, not just a number.
+  - prompt: "quins KPIs triem per al nostre producte SaaS?"
+    why: Catalan trigger — 'which KPIs do we pick for our SaaS product', the metric-selection decision.
+  - prompt: "Audit our dashboard metrics for vanity numbers and tell us which ones are un-actionable."
+    why: Vanity-metric and actionability audit of existing KPIs — the reject/classify side of the skill.
+
+should_not_trigger:
+  - prompt: "Build the dashboard that displays our north-star metric."
+    route_to: dashboard
+    why: Displaying a chosen metric is a display/build task; kpi-framework only decides which metric.
+  - prompt: "Instrument the activation event in our app and set up the funnel."
+    route_to: analytics
+    why: Event instrumentation and funnels are analytics implementation, downstream of the metric decision.
+  - prompt: "Write the monthly metrics report for the board."
+    route_to: reporting
+    why: Producing the recurring narrative around numbers is reporting, not choosing the numbers.
+  - prompt: "Design an A/B test to lift our activation rate."
+    route_to: ab-testing
+    why: Designing an experiment to move an input is ab-testing; kpi-framework supplies the input to move.
+  - prompt: "Project our MRR forward 12 months given current growth."
+    route_to: forecasting
+    why: Projecting a metric over time is forecasting, not defining which metric matters.
+
+capability:
+  - scenario: "A seed-stage B2B SaaS team says 'we want more usage' and asks what they should measure. They have signups and total logins tracked, nothing else. Produce a metric definition doc."
+    must_include:
+      - One output north-star metric tied to retained/delivered value, expressed as a rate or ratio (not a raw count like total signups or total logins).
+      - 3-5 leading, directly controllable input drivers stated as concrete instrumentable events (e.g. % of new accounts reaching an activation milestone in week 1), not abstractions like 'engagement'.
+      - At least one guardrail/countermetric with the specific gaming risk it protects against named.
+      - A target for the north star with an explicit baseline, a calibrated magnitude (not 'double it'), a target date, and an owner.
+      - An explicit rejection of a vanity metric (e.g. total signups or total logins) with the reasoning for why it is rejected.
+      - A handoff note that instrumentation goes to analytics and display goes to dashboard.

package/skills/kpi-framework/references/definition-and-targets.md

@@ -0,0 +1,64 @@
+# Writing definitions, measuring baselines, and calibrating targets
+
+Depth offloaded from `SKILL.md` Steps 1-4. This is where a metric definition stops being a
+slogan and becomes a number two analysts compute identically.
+
+## Write an unambiguous definition
+
+A definition that drifts produces arguments instead of decisions. Every metric needs four
+components spelled out:
+
+1. **Event** — the exact tracked action. Not "uses the product"; "completes `core_action`
+   (a saved project with >=1 collaborator)".
+2. **Time window** — rolling vs calendar, and its length. "Weekly active" must say *rolling
+   7-day* or *calendar week*; they differ by ~15% on most products.
+3. **Denominator** — what you divide by. "Active teams" vs "all signed-up teams" vs "paying
+   teams" are three different metrics wearing the same name.
+4. **Segment** — who's included. New vs existing, paid vs trial, by plan or region. State it
+   even when it's "all", so the choice is explicit.
+
+- Bad: `weekly active users`
+- Good: `accounts with >=1 member completing core_action in a rolling 7-day window / accounts with an active subscription, all regions`
+
+Rule: prefer a **rate or ratio** over a raw count. Counts grow with time and size and mask
+decline; a rate normalizes and exposes health.
+
+## Measure the baseline first
+
+You cannot set a target without a baseline — "get to 50%" is empty until you know you're at
+12% or 48%.
+
+- Pull the metric over a stable recent period (typically the last 4-8 weeks, long enough to
+  smooth noise, short enough to reflect the current product).
+- Note **variance**, not just the point value. A metric bouncing 30-46% week to week has a
+  baseline *range*; a target inside that range is no target at all.
+- If the event isn't instrumented yet, the first deliverable is "instrument it and measure
+  4 weeks" — hand the event to `../analytics/SKILL.md`. Do not invent a target over an
+  unmeasured metric.
+
+## Calibrate the target magnitude
+
+Targets break in two directions: too ambitious (burnout, shortcuts, gaming) or sandbagged
+(no improvement, theatre).
+
+- **Improvement over baseline, not a round number.** Derive the band from (a) the levers you
+  actually have this period and (b) what comparable improvements have historically yielded.
+  "38% → 52%" grounded in a named initiative beats "→ 50%" chosen because it's round.
+- **Set a realistic band, then commit to a point.** E.g. "expect 48-55% from the onboarding
+  rework; commit to 52%." The band is your reasoning; the point is the target.
+- **Avoid round-number theatre.** 50%, 100%, 1M — round targets are usually chosen for how
+  they read in a deck, not because the levers support them. Treat a suspiciously round
+  target as unexamined until proven otherwise.
+- **Date + owner are mandatory.** No date → it's a wish. No owner → it's nobody's job.
+
+## Re-validation checklist (run semi-annually)
+
+- [ ] Does the north star still **predict** retention/revenue? Re-check the correlation
+      against the last two quarters; a metric can quietly stop predicting value.
+- [ ] Are the inputs still **controllable** by the owning team, and do they still move the
+      north star when pushed?
+- [ ] Has any guardrail crept toward its harm threshold while the target improved? (silent
+      gaming signal)
+- [ ] Did the product/portfolio change enough to retire or redefine a metric?
+- [ ] Version and date the doc; record what changed and why. Transparent evolution keeps a
+      metric shift from looking like cooking the numbers.

package/skills/kpi-framework/references/metric-catalog.md

@@ -0,0 +1,84 @@
+# Metric catalog — candidate north stars and driver sets by business type
+
+A lookup table, not a flow. Use it to seed candidates in Step 1 and Step 2, then narrow
+to **one** north star and **3-5** inputs for the actual team. AARRR and HEART are
+*candidate-generation lenses* — they help you find candidates, they are not the framework.
+Adapt every line to the specific business; do not copy a row verbatim.
+
+Every candidate north star below is a rate or ratio tied to delivered value, never a raw
+count. Every input is leading, controllable, and stated as a concrete instrumentable event.
+
+---
+
+## SaaS (product-led)
+
+- **Lens:** HEART (engagement + retention + adoption).
+- **Candidate north star:** weekly active accounts completing a *core action* / active accounts.
+  - Why a core action and not "logins": logins are presence, the core action is value delivered.
+- **Inputs (leading):**
+  - median time-to-first-core-action for new accounts
+  - % of new accounts reaching the activation milestone in week 1
+  - % of seats invited that activate within 7 days
+  - feature-X adoption among accounts that retain (if X correlates with retention)
+- **Guardrails:** support tickets per active account (must not rise); week-4 retention of newly-activated cohort (catches a loosened activation definition).
+
+## Marketplace (two-sided)
+
+- **Lens:** AARRR on both sides; liquidity is the real outcome.
+- **Candidate north star:** % of listings/requests that result in a successful match within N days (matched supply-demand), or successful transactions / active buyer.
+  - Why a match rate, not GMV: GMV grows with price inflation and one-off whales; match rate measures the marketplace actually clearing.
+- **Inputs (leading):**
+  - new supply with >=1 active listing in first 7 days
+  - search-to-contact rate (demand side)
+  - time-to-first-response from supply side
+  - repeat-request rate within 30 days
+- **Guardrails:** cancellation/dispute rate (catches forced or low-quality matches); supply churn (catches demand-side over-optimization that burns suppliers).
+
+## Content / media
+
+- **Lens:** HEART (engagement + happiness), explicitly *not* raw reach.
+- **Candidate north star:** weekly returning readers/viewers who consume >=N pieces / weekly actives, or completion-weighted engaged time per returning user.
+  - Why returning + depth, not page views: page views are the classic vanity metric — they spike on a viral fluke and predict nothing.
+- **Inputs (leading):**
+  - % of new visitors who return within 7 days
+  - subscriptions/follows from engaged sessions (not popups)
+  - content-completion rate per piece
+  - saves / adds-to-list per active user
+- **Guardrails:** unsubscribe + mute rate (catches notification spam); content-quality complaints (catches clickbait optimization).
+
+## E-commerce
+
+- **Lens:** AARRR (revenue + retention).
+- **Candidate north star:** repeat-purchase rate within 90 days, or contribution-margin-positive orders per active customer.
+  - Why repeat rate / margin, not revenue: top-line revenue hides discounting, returns, and one-time deal-chasers.
+- **Inputs (leading):**
+  - first-order-to-second-order conversion within 30 days
+  - cart-to-checkout completion rate
+  - email/SMS opt-in among purchasers
+  - product-page-to-cart rate for in-stock items
+- **Guardrails:** refund + return rate (catches aggressive upsell); CAC payback (hand economics to `../unit-economics/SKILL.md`).
+
+## B2B sales-led
+
+- **Lens:** AARRR adapted to a longer cycle; the outcome is qualified pipeline that closes.
+- **Candidate north star:** SQL-to-closed-won rate, or net revenue retention of the existing book.
+  - Why a conversion/retention rate, not "leads": lead count is vanity when leads don't convert; the win rate and NRR are where value lives.
+- **Inputs (leading):**
+  - MQL-to-SQL conversion rate
+  - % of opportunities with a completed discovery/qualification step
+  - time-in-stage for the slowest pipeline stage
+  - product activation within the trial/POC window
+- **Guardrails:** discount depth on closed-won (catches "win at any price"); 90-day post-sale churn (catches over-promising to close).
+
+---
+
+## How to use a row
+
+1. Pick the lens that matches how your product creates value.
+2. Take the candidate north star, rewrite it for your exact core action and denominator.
+3. Steal 3-5 inputs, cut to the ones your team can actually ship against this quarter.
+4. Take the guardrails as a starting countermetric set; add any harm specific to your push.
+5. Move to Step 4 in `SKILL.md` to baseline and target each row.
+
+If your business doesn't fit a row, build one: ask what single outcome predicts that next
+year's customers stay, then ask which 3-5 plays the team controls that cause it.