rsc-universal 0.1.1

package/skills/typescript/references/type-system.md

@@ -0,0 +1,162 @@
+# Type-system deep dives
+
+Recipes the SKILL body points to. All target TypeScript 5.9. Read the relevant section, not
+the whole file.
+
+## Conditional types + `infer`
+
+`infer` introduces a type variable inside the `extends` clause and binds it to whatever
+matched. It is how you destructure types positionally.
+
+```ts
+type ElementOf<T> = T extends readonly (infer U)[] ? U : never;
+type Unwrap<T> = T extends Promise<infer U> ? Unwrap<U> : T; // recursive unwrap of nesting
+type FirstArg<F> = F extends (a: infer A, ...rest: any[]) => any ? A : never;
+```
+
+Distributive conditional types: when the checked type is a *naked* type parameter and the
+input is a union, the conditional distributes over each member. Wrap both sides in a tuple to
+turn it off.
+
+```ts
+type ToArray<T> = T extends any ? T[] : never;
+type A = ToArray<string | number>;   // string[] | number[]  (distributed)
+type NonDist<T> = [T] extends [any] ? T[] : never;
+type B = NonDist<string | number>;   // (string | number)[]  (not distributed)
+```
+
+## Mapped types: key remapping, modifiers
+
+```ts
+// Remap keys with `as` + template literals; filter by mapping to never.
+type Getters<T> = { [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K] };
+type RemoveId<T> = { [K in keyof T as K extends "id" ? never : K]: T[K] };
+
+// Modifiers: + / - add or strip readonly and optional.
+type Mutable<T>  = { -readonly [K in keyof T]: T[K] };
+type Concrete<T> = { [K in keyof T]-?: T[K] }; // strip optionality
+```
+
+## Template-literal types
+
+```ts
+type Route = `/${string}`;                       // any path-ish string
+type Method = "GET" | "POST" | "PUT" | "DELETE";
+type Endpoint = `${Method} ${Route}`;            // "GET /users", ...
+type CSSVar = `--${string}`;
+// Inference inside templates:
+type ParseId<T> = T extends `user_${infer N}` ? N : never; // ParseId<"user_42"> = "42"
+```
+
+## Recursive types (with care)
+
+Recursion is allowed but the depth is bounded by the instantiation-depth limit; deep tuple
+recursion (e.g. length-N tuples) hits it fast. Prefer tail-recursive accumulator patterns.
+
+```ts
+type DeepReadonly<T> = T extends (infer U)[]
+  ? readonly DeepReadonly<U>[]
+  : T extends object
+    ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
+    : T;
+```
+
+## Variance: `in` / `out` annotations
+
+TS infers variance structurally; you can annotate it on type parameters to make intent
+explicit and speed up checking on large generic types.
+
+- **Covariant** (`out T`): T appears only in output position (return types, readonly props).
+- **Contravariant** (`in T`): T appears only in input position (parameters).
+- **Invariant** (`in out T`): both.
+
+```ts
+interface Consumer<in T> { consume(value: T): void; }     // contravariant
+interface Producer<out T> { produce(): T; }               // covariant
+```
+
+Method parameters are checked **bivariantly** by default for legacy reasons;
+`strictFunctionTypes` makes standalone function-type parameters strictly contravariant, but
+**method** shorthand stays bivariant — prefer the `prop: (x: T) => U` arrow form when you
+want strict checking.
+
+## Branded / nominal patterns
+
+Structural typing means two aliases of `string` are interchangeable. Brand to forbid mixing:
+
+```ts
+declare const brand: unique symbol;
+type Brand<T, B> = T & { readonly [brand]: B };
+
+type UserId = Brand<string, "UserId">;
+type Cents  = Brand<number, "Cents">;
+
+const userId = (s: string): UserId => s as UserId; // brand only after validation
+function charge(amount: Cents) {}
+// charge(100);            // error: number is not Cents
+// charge(userId("u1"));   // error: UserId is not Cents
+```
+
+The brand exists only at the type level (zero runtime cost). Apply the cast in exactly one
+validated constructor, never sprinkle `as UserId` across the codebase.
+
+## Declaration merging
+
+Interfaces with the same name merge; this is how you augment third-party or global types.
+
+```ts
+// Augment a module's types without forking it.
+declare module "express" {
+  interface Request { userId?: string; }
+}
+// Augment globals.
+declare global {
+  interface Window { __APP_VERSION__: string; }
+}
+export {}; // make this file a module so `declare global` is allowed
+```
+
+`type` aliases do **not** merge — only `interface` and `namespace` do.
+
+## Function overloads
+
+Provide multiple call signatures, one implementation signature (which is not callable). Order
+overloads most-specific first.
+
+```ts
+function toArray(x: string): string[];
+function toArray(x: number): number[];
+function toArray(x: string | number): (string | number)[] {
+  return [x];
+}
+```
+
+Prefer a single generic or a union return over overloads when the relationship is
+expressible — overloads don't compose and don't infer across each other.
+
+## Type predicates & assertion functions
+
+```ts
+// Type predicate: narrows the argument when it returns true.
+function isString(x: unknown): x is string { return typeof x === "string"; }
+
+// Assertion function: narrows by throwing otherwise (note the `asserts` keyword).
+function assertDefined<T>(x: T): asserts x is NonNullable<T> {
+  if (x == null) throw new Error("expected a value");
+}
+
+const v: string | undefined = maybe();
+assertDefined(v);
+v.toUpperCase(); // v is string here
+```
+
+TS 5.5+ infers type predicates for simple filter callbacks, so
+`arr.filter((x) => x != null)` now narrows to `T[]` without a hand-written predicate in many
+cases — but an explicit predicate is still clearer for non-trivial checks.
+
+## `const` type parameters & `NoInfer`
+
+```ts
+function widen<const T>(x: T): T { return x; }         // keeps literals, no `as const`
+function build<T>(items: T[], fallback: NoInfer<T>) {} // fallback can't drive inference of T
+```

package/skills/typescript/scripts/verify.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# verify.sh — prove the TS toolchain enforces strictness + exhaustiveness.
+# Read-only on the target: writes ONLY to its own temp dir. Exits 0 with a clear
+# message when no TS/node is available (no false failure on a clean machine).
+set -euo pipefail
+
+# Resolve a type-checker: prefer tsgo (TS7 preview), else npx typescript's tsc.
+# Strict flags are passed on the CLI because naming files on the CLI bypasses tsconfig.
+FLAGS="--noEmit --strict --noUncheckedIndexedAccess --target esnext --module nodenext --moduleResolution nodenext"
+if command -v tsgo >/dev/null 2>&1; then
+  CHECK="tsgo"
+elif command -v npx >/dev/null 2>&1; then
+  CHECK="npx -y -p typescript tsc"
+else
+  echo "SKIP: no tsgo and no npx on PATH — cannot type-check. (exit 0)"
+  exit 0
+fi
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+# good.ts: exhaustive never guard MUST pass.
+cat > "$TMP/good.ts" <<'TS'
+type S = { k: "a" } | { k: "b" };
+export function f(s: S): number {
+  switch (s.k) {
+    case "a": return 1;
+    case "b": return 2;
+    default: { const _: never = s; return _; }
+  }
+}
+TS
+
+# bad.ts: missing "b" case -> never guard MUST fail to compile.
+cat > "$TMP/bad.ts" <<'TS'
+type S = { k: "a" } | { k: "b" };
+export function f(s: S): number {
+  switch (s.k) {
+    case "a": return 1;
+    default: { const _: never = s; return _; }
+  }
+}
+TS
+
+run() { ( cd "$TMP" && $CHECK $FLAGS "$1" ) >/dev/null 2>&1; }
+
+fail=0
+if run good.ts; then echo "PASS: good.ts type-checks"; else echo "FAIL: good.ts should compile"; fail=1; fi
+if run bad.ts;  then echo "FAIL: bad.ts should NOT compile (exhaustiveness)"; fail=1; else echo "PASS: bad.ts rejected"; fi
+
+if [ "$fail" -ne 0 ]; then echo "verify.sh: FAILED"; exit 1; fi
+echo "verify.sh: OK — strict + exhaustiveness enforced"

package/skills/unit-economics/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: unit-economics
+description: "Use when computing or improving the per-customer economics of a business — CAC, LTV, CAC payback period, contribution margin — or judging whether LTV:CAC and payback are healthy against 2025-2026 norms, and naming the one lever that fixes the worst number. Triggers: 'what's our CAC / LTV / payback', 'is our LTV:CAC ratio healthy', 'our payback period feels too long', 'is a 5:1 LTV:CAC actually good', 'our blended CAC looks fine but I think paid is bleeding money', 'the model says we're profitable but each customer feels like a loss — what's the contribution margin per customer', 'calcula'm el CAC i quant trigo a recuperar el cost d'un client', 'el ratio LTV:CAC és sa?', 'margen de contribución por cliente'. NOT the multi-year P&L / scenario projection (that is financial-model)."
+tags: ["cac", "ltv", "payback-period", "contribution-margin", "unit-economics", "ltv-cac-ratio", "nrr", "saas-metrics"]
+recommends: ["financial-model", "pricing", "retention", "cost-tracking", "forecasting", "investor-materials", "dashboard"]
+origin: risco
+---
+
+# Unit economics
+
+Answer one question honestly: **does one customer pay back more than it cost to win and serve them, and how fast?** You compute four load-bearing numbers — CAC, contribution margin, LTV, CAC payback period — plus the two ratios operators and investors actually argue about (LTV:CAC, NRR). Then you diagnose *why* a number is where it is and name the single lever that moves it.
+
+This is a measurement-and-diagnosis skill, not a projection skill. You do not build the multi-year model here (that is the `financial-model` sibling); you build the per-customer truth that the model's growth assumptions have to rest on.
+
+## What this skill produces
+
+A **unit-economics worksheet** (`unit-economics.{yaml,csv,md}`) where:
+- a block of **named inputs** — period S&M spend, new customers, monthly ARPA, gross margin %, monthly churn, optional segment rows — is stated explicitly;
+- every **derived figure** (CAC, contribution margin, LTV, payback, LTV:CAC) is recomputed *from those inputs* so the relationships are self-consistent;
+- the worst number is diagnosed and one concrete lever is prescribed.
+
+`scripts/verify.sh` re-derives the figures and fails if the arithmetic lies (see the last section). If you only hand back prose, you have not finished — emit the worksheet.
+
+## The four numbers and the input people get wrong
+
+Each formula has one input that, done sloppily, silently invalidates everything downstream. Tag the input, not just the result.
+
+| Number | Formula | The input people get wrong |
+|---|---|---|
+| **CAC** | fully-loaded S&M spend ÷ new customers (same period) | the *numerator* — ad-spend-only CAC understates true CAC ~3.5× |
+| **Contribution margin / customer** | ARPA − variable cost to serve (COGS + variable support + payment fees) | confusing it with company-wide gross margin % |
+| **LTV** | (ARPA × Gross Margin %) ÷ churn rate | using *revenue* instead of *gross-margin* dollars |
+| **CAC payback (months)** | CAC ÷ (monthly ARPA × Gross Margin %) | leaving gross margin out of the denominator |
+
+**Worked Bad → Good — the revenue-LTV inflation.** Same inputs: ARPA $400/mo, gross margin 75%, monthly churn 3%.
+
+```text
+Bad  (revenue LTV):       400 / 0.03          = $13,333   <- overstates by 33%
+Good (gross-margin LTV): (400 * 0.75) / 0.03  = $10,000   <- what a customer is actually worth
+```
+
+LTV must use gross-margin dollars because not all revenue is profit — hosting, support, and payment fees come out first. The revenue version flatters the LTV:CAC ratio and is the single most common dishonesty in a deck. (Beancount.io "2026 SaaS Metrics Stack" 2026-05-10; ChartMogul LTV guide; both accessed 2026-06-02.)
+
+Full derivations, cohort-LTV vs formula-LTV, the Skok discounted model, and segment roll-up math live in `references/formulas.md`. Read it before you defend a number to an investor.
+
+## Order of operations (the spine)
+
+Run these in order — each step is an input to the next, so skipping one makes everything after it fiction.
+
+1. **Gross margin first.** Every downstream metric multiplies by it. If gross margin is unknown, the COGS per unit must be tracked first (route to `cost-tracking`) — you cannot compute LTV or payback on a guessed margin.
+2. **CAC, fully loaded.** Include all sales + marketing cost; exclude customer-success/retention spend and returning customers.
+3. **Contribution margin per customer.** ARPA minus variable cost to serve — the dollars that actually pay back CAC.
+4. **LTV, capped.** Gross-margin LTV with a lifetime cap (see conservatism), not 1/churn run to infinity.
+5. **Payback period.** CAC ÷ monthly contribution margin.
+6. **Ratios.** LTV:CAC and NRR/GRR for context.
+7. **Diagnose & prescribe.** Find the worst number, name its cause, name the lever.
+
+## Get the inputs honest
+
+CAC is fully loaded or it is a lie. Decide what goes in the numerator before you divide.
+
+| In the CAC numerator | Out of the CAC numerator |
+|---|---|
+| Sales + marketing salaries & benefits | Customer-success / retention spend (that protects LTV, it doesn't acquire) |
+| Sales commissions & SDR/AE comp | R&D / product engineering |
+| Ad spend, content, events, agencies | Overhead/G&A not tied to acquisition |
+| Marketing & sales tooling | (Denominator) returning / reactivated customers — only count *new* logos |
+| Founder selling time (impute a salary) | |
+
+Three rules that catch most errors:
+
+- **Gross margin, not opex margin.** Gross margin reflects COGS (hosting, support, payment fees), not salaries/rent. Mixing in opex understates margin and quietly tanks LTV. (Beancount.io 2026-05-10, accessed 2026-06-02.)
+- **Match time units.** Monthly ARPA pairs with monthly churn; annual with annual. Mixing them silently 12×'s or ÷12's the LTV — the most common arithmetic error in the whole exercise. (ChartMogul; metrickit LTV guide; accessed 2026-06-02.)
+- **Right period, right denominator.** Spend in period P ÷ customers acquired in period P. Don't divide this quarter's spend by all-time customers.
+
+## Segment before you optimize
+
+A single blended number hides the only insight that matters. Reporting one blended CAC of $1,200 when self-serve is $80 and field sales is $40,000 tells you nothing actionable — the channels have wildly different CAC, ARPA, and churn. (lucid.now LTV/CAC errors; andrewchen; accessed 2026-06-02.)
+
+```text
+Blended CAC $1,200  =  self-serve $80  +  inside sales $900  +  field $40,000
+                       (lever: scale)   (lever: AE ramp)      (lever: ACV / cycle)
+```
+
+Two more separations to keep clean:
+- **Paid CAC vs blended CAC.** Blended includes free/organic; paid isolates the channels you can actually scale with money. Optimize paid; report both.
+- **Self-serve / inside sales / field sales.** Split on go-to-motion, because the lever for each is different. If one segment is bleeding while blended "looks fine," that's exactly the non-obvious failure this skill exists to surface.
+
+## Benchmarks (2025-2026)
+
+A ratio is a conversation-starter, not a pass/fail grade. Read the whole row before you celebrate or panic.
+
+| Metric | Elite / top quartile | Healthy / median | Concern |
+|---|---|---|---|
+| CAC payback | < 12 months | B2B SaaS median 12-18 mo | 24+ months = sustainability concern |
+| Payback by ACV | ~9 mo at ACV ≤ $5K | — | ~24 mo at ACV > $100K (expected, not bad) |
+| LTV:CAC | 3:1 to 5:1 | median B2B ≈ 3.2:1 | < 3:1 overspending; **> 5:1 under-investing in growth** |
+| NRR | top quartile 115-125% | healthy 105-115% | < 100% net contraction |
+| GRR | — | — | high NRR + low GRR = expansion masking churn |
+
+(Beancount.io 2026-05-10; First Page Sage CAC Payback Benchmarks 2025; Optifai B2B LTV benchmark, 939 companies; cast.app NRR; all accessed 2026-06-02.)
+
+The honest framing: a **2.5:1 with 9-month payback and 120% NRR beats a 4:1 with 36-month payback and 95% NRR.** Payback and NRR decide whether you can survive the gap between spend and return; the ratio alone can't. **Rule of 40** (ARR growth % + profit margin % ≥ 40%) is the company-level destination these feed — cite it, but compute it in `financial-model`, not here.
+
+## Diagnose & prescribe (this is where the flow branches)
+
+Find the worst number, then route to the lever — and to the sibling skill that owns that lever.
+
+| Bad number | Likely cause | Lever (and owner) |
+|---|---|---|
+| CAC too high | wrong channel mix / paid-heavy | shift to founder-led & organic; cut the bleeding channel — diagnose by segment here, then `pricing` if the fix is monetization |
+| Payback too long | low margin-dollar capture per month | move to annual prepay; shorten free trial; lift gross margin (`cost-tracking` for COGS) |
+| LTV too low | dominant churn term | attack the biggest churn driver → `retention`; lift expansion to push NRR > 100% |
+| Margin too low | COGS per unit too high | instrument per-unit COGS / inference cost → `cost-tracking` |
+| LTV:CAC > 5:1 | under-investing in growth | spend *more* on acquisition — you're leaving money on the table, not winning |
+| NRR ≫ GRR | expansion masking a churn problem | fix gross retention first → `retention`; don't let expansion hide the leak |
+
+The skill stops at "here is the worst number and the lever." Executing the lever (set the price, design the save-play, project the new curve) belongs to the sibling, not here.
+
+## Conservatism rules (so LTV isn't fantasy)
+
+Small churn errors explode LTV because of the 1/churn term — at 1% monthly churn the formula implies a ~100-month (8+ year) lifetime, which no early-stage company has data to claim.
+
+- **Cap assumed lifetime at 3-4 years** for early-stage (≤ 48 months), or apply a **×0.7 conservatism multiplier** to formula LTV.
+- **Cohort beats formula.** Once you have multi-year retention data, compute cohort LTV from observed retention — the formula is a placeholder until then.
+- **Discount future value** in the advanced (Skok) model: ~20-25% discount rate pre-scale, ~10% at scale, because a dollar of contribution margin three years out is worth less than one today.
+- **NRR > 100% means the simple churn-only LTV understates** the cohort — note it rather than silently leaving value on the table.
+
+(Beancount.io 2026-05-10; metrickit LTV guide; forEntrepreneurs SaaS Metrics 2.0; all accessed 2026-06-02.) Worked discounted and cohort examples are in `references/formulas.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| Revenue LTV (ARPA ÷ churn) | overstates value; not all revenue is profit | gross-margin LTV: (ARPA × GM%) ÷ churn |
+| Ad-spend-only CAC | understates true CAC ~3.5× | fully-loaded S&M ÷ new customers |
+| Monthly ARPA with annual churn | silently 12×'s or ÷12's the LTV | match time units before dividing |
+| Near-zero churn → 30-year lifetime | fantasy LTV no one can back with data | cap lifetime ≤ 48 mo or ×0.7 multiplier |
+| One blended CAC/LTV | hides self-serve vs field; nothing actionable | segment by go-to-motion first |
+| Counting CS/retention spend in CAC | inflates CAC; that spend protects LTV, doesn't acquire | keep CS out of the numerator |
+| Reading only the LTV:CAC ratio | ignores payback & NRR that decide survivability | read payback + NRR alongside the ratio |
+| Quoting NRR while GRR is weak | expansion masks a churn leak | report GRR floor too; fix retention first |
+
+## The worksheet format
+
+Emit this so the numbers are checkable, not just asserted:
+
+```yaml
+# unit-economics.yaml
+inputs:
+  period_sm_spend: 120000      # fully-loaded S&M, this period
+  new_customers: 80            # new logos only, same period
+  monthly_arpa: 400
+  gross_margin_pct: 0.75
+  monthly_churn: 0.03          # monthly, to match monthly_arpa
+  # lifetime_cap_override: 60  # only if you justify > 48 months
+outputs:
+  cac: 1500                    # 120000 / 80
+  contribution_margin: 300     # 400 * 0.75
+  ltv: 10000                   # (400 * 0.75) / 0.03   (NOT 13333)
+  payback_months: 5            # 1500 / (400 * 0.75)
+  ltv_cac: 6.67                # 10000 / 1500  -> >5: under-investing
+segments:                      # split when blended hides the truth
+  - name: self-serve
+    cac: 80
+  - name: field-sales
+    cac: 40000
+```
+
+`scripts/verify.sh` parses this file and **fails if**: CAC ≠ spend ÷ new_customers; contribution_margin ≠ ARPA × GM%; payback ≠ CAC ÷ (ARPA × GM%); the stated LTV matches the *revenue* form instead of the gross-margin form; ltv_cac ≠ LTV ÷ CAC within 0.05; or implied lifetime (1/churn) > 48 months with no `lifetime_cap_override`. It is read-only and exits 0 on a clean worksheet (and on no worksheet at all).
+
+## Where this hands off
+
+- Multi-year P&L / scenario / cap-table model → `financial-model`.
+- Setting the actual price, tiers, discount floor → `pricing`.
+- Churn-prevention program (health scores, save-plays, win-back) → `retention`.
+- Per-unit COGS / infra / AI inference cost so gross margin is even knowable → `cost-tracking`.
+- Forecasting future MRR / cohort projection → `forecasting`.
+- Writing the investor unit-economics narrative / data-room exhibit → `investor-materials`.
+- Generic KPI chart / dashboard surface → `dashboard`.

package/skills/unit-economics/evals/README.md

@@ -0,0 +1,5 @@
+# Evals — unit-economics
+
+These cases are read, not executed. To run them by eye: for each `should_trigger` prompt, confirm the skill's `description` would plausibly fire on it (the non-obvious "blended CAC looks fine but paid is bleeding" and the Catalan payback case are the ones to watch — they never name a metric). For each `should_not_trigger` prompt, confirm the request belongs to the named `route_to` sibling instead (financial-model for the multi-year model, pricing for setting the price, retention for save-plays, cost-tracking for per-unit COGS, forecasting for cohort projection).
+
+The `capability` case is graded by handing the scenario to the agent and checking its answer against the `must_include` rubric: correct CAC ($1,500), gross-margin LTV ($10,000, not the $13,333 revenue version, with the difference flagged), payback in months (5), the >5:1 under-investing read on the 6.67:1 ratio, a conservatism/lifetime-cap note, segmentation advice, and an actual recomputable worksheet rather than prose. A worksheet emitted to `unit-economics.yaml` should additionally pass `scripts/verify.sh` clean.

package/skills/unit-economics/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: unit-economics
+
+should_trigger:
+  - prompt: "What's our CAC and LTV, and is the LTV:CAC ratio healthy?"
+    why: "Canonical trigger — compute the core numbers plus benchmark the ratio; the skill's center of gravity."
+  - prompt: "Our payback period feels too long — how do I bring it down?"
+    why: "Diagnosis + lever, not just a calculation; routes to annual prepay / margin levers via the diagnose table."
+  - prompt: "Calcula'm el CAC i quant trigo a recuperar el cost d'un client."
+    why: "Catalan; 'quant trigo a recuperar el cost' is the payback-period phrasing without naming the metric in English."
+  - prompt: "Our blended CAC looks fine but I think paid is bleeding money — can we check?"
+    why: "NON-OBVIOUS — the user never says 'unit economics' or 'segment'; this is exactly the paid-vs-blended / segmentation failure the skill surfaces."
+  - prompt: "The model says we're profitable but each customer feels like a loss — what's the contribution margin per customer?"
+    why: "Contribution-margin entry point; surfaces the per-unit truth against a whole-company P&L that looks fine."
+  - prompt: "Is a 5:1 LTV:CAC actually good or are we under-investing in growth?"
+    why: "Benchmark interpretation — the >5:1 under-investing caveat that most rules-of-thumb miss."
+
+should_not_trigger:
+  - prompt: "Build me a 3-year revenue and P&L projection for the raise."
+    route_to: financial-model
+    why: "Multi-year projection / scenario engine, not the per-customer truth; the named boundary in the description."
+  - prompt: "What should we charge and how should we package the tiers?"
+    route_to: pricing
+    why: "Setting the actual price and packaging, not validating the economics of an existing price."
+  - prompt: "Design a churn save-play and win-back sequence for at-risk accounts."
+    route_to: retention
+    why: "Churn-prevention program design, not measuring churn's effect on LTV."
+  - prompt: "Figure out our per-request AI inference cost so we know gross margin."
+    route_to: cost-tracking
+    why: "Per-unit COGS instrumentation that feeds gross margin — upstream of this skill, not the same job."
+  - prompt: "Forecast next year's MRR from our cohort retention curves."
+    route_to: forecasting
+    why: "Time-series / cohort projection, not the per-customer ratios."
+
+capability:
+  - scenario: "Operator gives: period S&M spend $120K, 80 new customers, monthly ARPA $400, gross margin 75%, monthly churn 3%; one segment is self-serve, one is sales-led. Produce the unit-economics worksheet and diagnose."
+    must_include:
+      - "CAC = $1,500 (120000 / 80)."
+      - "Gross-margin LTV: (400 × 0.75) / 0.03 = $10,000, explicitly NOT the revenue LTV of $13,333, and flags the difference."
+      - "Payback = 1500 / (400 × 0.75) = 5 months (gross margin in the denominator)."
+      - "LTV:CAC = 6.67:1, flagged as possibly under-investing in growth because it exceeds 5:1."
+      - "Conservatism note: 3% monthly churn implies ~33-month life, within the 48-month cap; states the cap/×0.7 rule."
+      - "Recommends segmenting self-serve vs sales-led because blended hides the truth, and names the lever for the worst sub-metric."
+      - "Emits a worksheet (yaml/csv/md) with named inputs and recomputed outputs, not just prose."

package/skills/unit-economics/references/formulas.md

@@ -0,0 +1,144 @@
+# Unit-economics formulas — full derivations
+
+The SKILL.md body carries the spine. This file carries every derivation you need to defend a number, with worked examples on consistent units.
+
+All examples reuse one base case unless stated:
+
+```text
+period S&M spend = $120,000   new customers = 80
+monthly ARPA = $400           gross margin = 75% (0.75)
+monthly churn = 3% (0.03)
+```
+
+## 1. CAC — fully loaded
+
+```text
+CAC = (all sales + marketing cost in period) / (new customers acquired in same period)
+    = 120000 / 80
+    = $1,500
+```
+
+Numerator includes salaries, benefits, commissions, ad spend, content, events, agencies, tooling, and imputed founder selling time. It excludes customer-success/retention spend (that protects existing LTV) and R&D. Ad-spend-only CAC commonly understates true CAC by ~3.5×. Denominator counts new logos only — exclude returning/reactivated customers.
+
+Keep two CACs:
+- **Paid CAC** = paid-channel spend ÷ customers from paid channels (the part you scale with money).
+- **Blended CAC** = all S&M ÷ all new customers (includes free/organic).
+
+## 2. Contribution margin per customer
+
+```text
+contribution_margin = ARPA - variable_cost_to_serve
+                    = ARPA - (COGS + variable support + payment/processing fees)
+                    = 400 * 0.75            # when GM% already nets out variable cost
+                    = $300 / month
+```
+
+Distinct from **gross margin %**, which is the company-wide ratio. Contribution margin is the per-customer dollar figure that actually pays back CAC and funds opex. LTV is the (discounted) stream of this contribution margin over the customer's life.
+
+## 3. LTV — gross-margin, not revenue
+
+Consistent monthly units throughout:
+
+```text
+gross-margin LTV = (monthly ARPA * GM%) / monthly churn
+                 = (400 * 0.75) / 0.03
+                 = 300 / 0.03
+                 = $10,000
+
+revenue LTV (WRONG) = 400 / 0.03 = $13,333   # overstates by 33%
+```
+
+Annual units must pair together:
+
+```text
+annual ARPA = 4800, annual churn = 30.4%  (1 - (1-0.03)^12)
+annual LTV = (4800 * 0.75) / 0.304 ≈ $11,842
+```
+
+Note the annual figure differs from the naive monthly×12 because compounding churn over 12 months exceeds 36%. When precision matters, derive annual churn from monthly via `1 - (1 - m)^12`, not `m * 12`.
+
+## 4. CAC payback period
+
+```text
+payback_months = CAC / (monthly ARPA * GM%)
+               = 1500 / (400 * 0.75)
+               = 1500 / 300
+               = 5 months
+```
+
+The denominator is monthly contribution margin. Leaving GM% out (`1500 / 400 = 3.75`) understates payback and is a common error.
+
+## 5. LTV:CAC
+
+```text
+LTV:CAC = LTV / CAC = 10000 / 1500 = 6.67 : 1
+```
+
+Interpretation against 2025-2026 norms: 3:1-5:1 healthy; < 3:1 overspending on acquisition; **> 5:1 under-investing in growth** (6.67:1 here → spend more). Median B2B SaaS ≈ 3.2:1. The ratio is a conversation, not a grade — pair it with payback and NRR.
+
+## 6. Lifetime cap & conservatism
+
+Implied lifetime from churn:
+
+```text
+implied_lifetime_months = 1 / monthly_churn = 1 / 0.03 ≈ 33.3 months   # within the 48-mo cap
+```
+
+At 1% monthly churn, `1/0.01 = 100 months` (8+ years) — fantasy for an early-stage company. Apply one of:
+
+- **Hard cap** at 36-48 months: `capped_LTV = min(formula_LTV, contribution_margin * cap_months)`.
+- **Conservatism multiplier**: `conservative_LTV = formula_LTV * 0.7`.
+
+```text
+base case capped LTV = min(10000, 300 * 48) = min(10000, 14400) = 10000   # cap not binding
+×0.7 conservative    = 10000 * 0.7 = $7,000
+```
+
+## 7. Skok discounted LTV (advanced)
+
+A dollar of contribution margin years out is worth less today. Discount the stream:
+
+```text
+LTV = sum over t of [ contribution_margin_t * retention_t / (1 + d)^t ]
+```
+
+with discount rate `d` ≈ 20-25% pre-scale, ≈ 10% at scale. Use this once you can model the retention curve `retention_t`; before that, the capped formula LTV is the honest placeholder.
+
+## 8. NRR / GRR worked example
+
+```text
+Start MRR = 100,000
++ expansion = 12,000
+- contraction = 3,000
+- churn = 5,000
+
+NRR = (100000 + 12000 - 3000 - 5000) / 100000 * 100 = 104%
+GRR = (100000 - 3000 - 5000) / 100000 * 100        = 92%   # no expansion
+```
+
+Healthy NRR 105-115%, top quartile 115-125%. GRR is the true floor. Here NRR 104% looks fine but GRR 92% means **8% gross monthly leakage masked by expansion** — fix gross retention (route to `retention`) before celebrating NRR. When NRR > 100%, the simple churn-only LTV understates the cohort's true value; note it.
+
+## 9. Segment roll-up
+
+Never average segment CACs naively — weight by customers.
+
+```text
+blended CAC = total S&M / total new customers
+            = (self_serve_spend + inside_spend + field_spend)
+              / (self_serve_n + inside_n + field_n)
+```
+
+Example: self-serve $80 (500 customers), field $40,000 (10 customers).
+
+```text
+blended = (80*500 + 40000*10) / (500 + 10)
+        = (40000 + 400000) / 510
+        = 440000 / 510
+        ≈ $863
+```
+
+The $863 blended number is real but useless for action — the levers (scale self-serve, fix field ACV/cycle) live in the segments, not the blend. Always segment before you optimize.
+
+## Sources
+
+Beancount.io "2026 SaaS Metrics Stack" (2026-05-10); ChartMogul LTV guide; metrickit LTV guide; andrewchen "How To (Actually) Calculate CAC"; First Page Sage SaaS CAC Payback Benchmarks 2025; Drivetrain CAC payback glossary; Optifai B2B SaaS LTV benchmark (939 companies); lucid.now LTV vs CAC errors; TZS Digital CAC deep dive; cast.app NRR; WallStreetPrep LTV/CAC; forEntrepreneurs SaaS Metrics 2.0. All accessed 2026-06-02.