marketing-mindset 1.12.0 → 1.13.0

package/README.md

@@ -200,3 +200,28 @@ The floor comes from the same formula as `sample`, and the arms split the earlie
 so a unit chosen here, a queue planned with `queue` and a result read with `verdict` stay consistent.
 Two things it refuses to hide: the earliest step reads soonest and owns the least, and money always reads
 one step behind whatever unit you chose.
+
+## `fit` — which channel can actually fund a verdict
+
+Two channels can both be worth testing and only one of them can be read this quarter. `fit` takes
+`name:contacts_per_month:cost_per_contact` for each channel, applies the same floor as `sample`, and
+says which channel reaches that floor inside the horizon and what one readable test costs there.
+
+```bash
+npx marketing-mindset fit --channels email:9000:0.02,linkedin:1200:0.35,seo:30000:0.005
+```
+```
+email: 9,000 contacts a month at 0.02 per contact -> floor 13,914 per arm, 4,500 events per arm a month, 4 month(s) to a verdict, one test 556.56, fits: yes
+linkedin: 1,200 contacts a month at 0.35 per contact -> floor 13,914 per arm, 600 events per arm a month, 24 month(s) to a verdict, one test 9739.8, fits: no
+seo: 30,000 contacts a month at 0.005 per contact -> floor 13,914 per arm, 15,000 events per arm a month, 1 month(s) to a verdict, one test 139.14, fits: yes
+first to run: seo - 139.14 for one readable test in 1 month(s)
+```
+
+At a 3% base rate and a +20% relative lift the floor is 13,914 contacts per arm on every channel, so the
+channel is not chosen by a better conversion rate but by how fast it can deliver those contacts and what
+each contact costs. `--json` returns the same object: one entry per channel with `floor_per_arm`,
+`events_per_arm_per_month`, `months_to_verdict`, `cost_per_arm`, `cost_per_test` and `fits`, plus
+`first_to_run`, `unreadable_channels` and three gates. `first_to_run` is the fitting channel with the
+lowest `cost_per_test`, ties broken by fewest months; when no channel fits it is a sentence saying so.
+Two things it refuses to hide: the floor is set by the base rate and the lift rather than by the channel,
+and a cheap contact list that cannot reach the floor inside the horizon funds nothing.

package/bin/cli.js

@@ -7,6 +7,7 @@
  *   marketing-mindset verdict        read a finished test: interval, floor, honest verdict
  *   marketing-mindset queue          volume into a queue of honest tests with read-out dates
  *   marketing-mindset cost           the cost of one readable verdict, and funded tests per budget
+ *   marketing-mindset fit            which channel can actually fund a verdict inside a horizon
  *   marketing-mindset unit           which funnel step can fund a verdict, and in how many months
  *   marketing-mindset sections       list every section of SKILL.md
  *   marketing-mindset read <text>    print one section by fuzzy title match
@@ -730,6 +731,125 @@ function runUnit(opts) {
   return 0;
 }
 
+var FIT_ZA = { "0.05": 1.9599639845, "0.01": 2.5758293036, "0.1": 1.6448536270 };
+var FIT_ZB = { "0.8": 0.8416212336, "0.9": 1.2815515655 };
+function fitRound2(x) { return Math.round(x * 100) / 100; }
+function fitFloor(rate, lift, power, alpha) {
+  const p1 = Math.min(Math.max(rate, 0.000001), 0.999999);
+  const p2 = Math.min(p1 * (1 + lift), 0.999999);
+  const pbar = (p1 + p2) / 2;
+  const za = FIT_ZA[String(alpha)] || FIT_ZA["0.05"];
+  const zb = FIT_ZB[String(power)] || FIT_ZB["0.8"];
+  const num = Math.pow(za * Math.sqrt(2 * pbar * (1 - pbar)) + zb * Math.sqrt(p1 * (1 - p1) + p2 * (1 - p2)), 2);
+  return Math.ceil(num / Math.pow(p2 - p1, 2));
+}
+function planFit(input) {
+  const channels = input.channels || [];
+  const base = Number(input.base !== undefined ? input.base : 0.03);
+  const lift = Number(input.lift !== undefined ? input.lift : 0.2);
+  const power = Number(input.power !== undefined ? input.power : 0.8);
+  const alpha = Number(input.alpha !== undefined ? input.alpha : 0.05);
+  const horizon = Number(input.horizon !== undefined ? input.horizon : 6);
+  const problems = [];
+  if (channels.length === 0) { problems.push("channels: pass --channels email:9000:0.02,linkedin:1200:0.35,seo:30000:0.005"); }
+  channels.forEach(function (c) {
+    if (!(Number(c.contacts_per_month) > 0)) { problems.push("contacts per month for '" + c.name + "' must be a positive number of contacts a month"); }
+    if (!(Number(c.cost_per_contact) >= 0)) { problems.push("cost per contact for '" + c.name + "' cannot be negative"); }
+  });
+  if (!(base > 0) || !(base < 1)) { problems.push("base rate: a number between 0 and 1 (0.03 = 3%)"); }
+  if (!(lift > 0) || !(lift < 5)) { problems.push("lift worth detecting: a fraction, 0.2 = +20% relative"); }
+  if (!FIT_ZB[String(power)]) { problems.push("power must be 0.8 or 0.9"); }
+  if (!FIT_ZA[String(alpha)]) { problems.push("alpha must be 0.05, 0.01 or 0.1"); }
+  if (!(horizon > 0)) { problems.push("horizon: months you are willing to wait, a positive number"); }
+  if (problems.length) { return { problems: problems }; }
+
+  const floor = fitFloor(base, lift, power, alpha);
+  const rows = channels.map(function (c) {
+    const perMonth = Number(c.contacts_per_month);
+    const cost = Number(c.cost_per_contact);
+    const events = perMonth / 2;
+    const months = Math.ceil(floor / events);
+    const costArm = fitRound2(floor * cost);
+    return {
+      channel: c.name, contacts_per_month: perMonth, cost_per_contact: cost,
+      floor_per_arm: floor, events_per_arm_per_month: events, months_to_verdict: months,
+      cost_per_arm: costArm, cost_per_test: fitRound2(costArm * 2), fits: months <= horizon
+    };
+  });
+  let best = null;
+  rows.forEach(function (c) {
+    if (!c.fits) { return; }
+    if (!best || c.cost_per_test < best.cost_per_test ||
+        (c.cost_per_test === best.cost_per_test && c.months_to_verdict < best.months_to_verdict)) { best = c; }
+  });
+  const none = "none of the listed channels can finish a verdict inside " + horizon + " month(s)";
+  const unreadable = rows.filter(function (c) { return !c.fits; }).map(function (c) { return c.channel; });
+  const gates = [
+    "the floor does not depend on the channel: " + fmtNum(floor) + " contacts per arm in every row, because it comes from the base rate and the lift",
+    best
+      ? "fund " + best.channel + " first: " + best.cost_per_test + " for one readable test (" + best.months_to_verdict + " month(s) at " + best.cost_per_contact + " per contact)"
+      : none + " - move the horizon or find a channel with more contacts",
+    unreadable.length
+      ? "out of reach inside " + horizon + " month(s): " + unreadable.join(", ")
+      : "every channel listed reaches a verdict inside " + horizon + " month(s)"
+  ];
+  return {
+    base_rate: base, lift: lift, power: power, alpha: alpha, horizon_months: horizon, floor_per_arm: floor,
+    channels: rows,
+    first_to_run: best ? best.channel : none,
+    first_to_run_cost_per_test: best ? best.cost_per_test : 0,
+    first_to_run_months: best ? best.months_to_verdict : 0,
+    unreadable_channels: unreadable, gates: gates
+  };
+}
+
+function runFit(opts) {
+  const spec = opts.channels;
+  const base = Number(opts.base !== undefined ? opts.base : 0.03);
+  const lift = Number(opts.lift !== undefined ? opts.lift : 0.2);
+  const power = Number(opts.power !== undefined ? opts.power : 0.8);
+  const alpha = Number(opts.alpha !== undefined ? opts.alpha : 0.05);
+  const horizon = Number(opts.horizon !== undefined ? opts.horizon : 6);
+  const problems = [];
+  let channels = [];
+  if (typeof spec !== "string" || !spec.trim()) {
+    problems.push("channels: pass --channels email:9000:0.02,linkedin:1200:0.35,seo:30000:0.005");
+  } else {
+    spec.split(",").forEach(function (part) {
+      const bits = part.trim().split(":");
+      if (bits.length !== 3 || !bits[0].trim() || !bits[1].trim() || !bits[2].trim() ||
+          !isFinite(Number(bits[1])) || !isFinite(Number(bits[2]))) {
+        problems.push("channels: '" + part.trim() + "' must look like name:contacts_per_month:cost_per_contact");
+      } else {
+        channels.push({ name: bits[0].trim(), contacts_per_month: Number(bits[1]), cost_per_contact: Number(bits[2]) });
+      }
+    });
+  }
+  if (problems.length) { console.error("fit: " + problems.join("; ")); return 1; }
+  const out = planFit({ channels: channels, base: base, lift: lift, power: power, alpha: alpha, horizon: horizon });
+  if (out.problems) { console.error("fit: " + out.problems.join("; ")); return 1; }
+  if (opts.json) { console.log(JSON.stringify(out, null, 2)); } else {
+    const head = ["channel", "contacts/mo", "cost/contact", "floor/arm", "events/arm/mo", "months", "cost/test", "fits"];
+    const rows = out.channels.map(function (c) {
+      return [c.channel, fmtNum(c.contacts_per_month), String(c.cost_per_contact), fmtNum(c.floor_per_arm),
+              fmtNum(c.events_per_arm_per_month), String(c.months_to_verdict), String(c.cost_per_test),
+              c.fits ? "yes" : "no"];
+    });
+    const widths = head.map(function (h, i) {
+      return Math.max(h.length, Math.max.apply(null, rows.map(function (r) { return r[i].length; })));
+    });
+    function pad(s, i) { return s + " ".repeat(widths[i] - s.length); }
+    console.log(head.map(pad).join("  "));
+    console.log(widths.map(function (w) { return "-".repeat(w); }).join("  "));
+    rows.forEach(function (r) { console.log(r.map(pad).join("  ")); });
+    console.log(out.first_to_run_cost_per_test
+      ? "first to run: " + out.first_to_run + " - " + out.first_to_run_cost_per_test + " for one readable test in " + out.first_to_run_months + " month(s)"
+      : "first to run: " + out.first_to_run);
+    out.gates.forEach(function (g) { console.log("gate: " + g); });
+  }
+  return 0;
+}
+
 function fmtNum(n) {
   return String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
 }
@@ -866,6 +986,8 @@ if (cmd === "sample") {
   process.exit(runQueue(flags(rest)));
 } else if (cmd === "unit") {
   process.exit(runUnit(flags(rest)));
+} else if (cmd === "fit") {
+  process.exit(runFit(flags(rest)));
 } else if (cmd === "cost") {
   process.exit(runCost(flags(rest)));
 } else if (cmd === "aeo") {
@@ -913,6 +1035,8 @@ Usage:
   npx marketing-mindset verdict         was the difference real, and was the volume ever enough?
   npx marketing-mindset queue           how many honest tests your volume can finish, and when each reads
   npx marketing-mindset cost            what one readable verdict costs to finish, and how many a budget funds
+  npx marketing-mindset fit             which channel can actually fund a verdict, and what one test costs there
+      --channels email:9000:0.02,linkedin:1200:0.35,seo:30000:0.005 [--base 0.03] [--lift 0.2] [--power 0.8] [--alpha 0.05] [--horizon 6] [--json]
   npx marketing-mindset unit            which step of your funnel can fund a verdict, and how many months it needs
       --steps visits:12000,signups:900,activations:270,paid:40 [--lift 0.2] [--power 0.8] [--alpha 0.05] [--horizon 6]
       --cost 0.02 --daily 500 [--budget 5000] [--base 0.03] [--lift 0.2] [--power 0.8] [--alpha 0.05]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "marketing-mindset",
-  "version": "1.12.0",
-  "description": "A marketer's operating mindset as an installable agent skill and CLI: test-size floors, kill rules, honest verdicts on finished tests, which funnel step can fund a verdict, the lift a volume can read, a queue of readable tests with read-out dates, the cost of one readable verdict. npx marketing-mindset sample|kill|verdict|unit|queue|cost|mde|budget|brief|plan|warmup|aeo|jd|sections|read|install.",
+  "version": "1.13.0",
+  "description": "A marketer's operating mindset as an installable agent skill and CLI: test-size floors, kill rules, honest verdicts on finished tests, which funnel step can fund a verdict, which channel can actually fund a verdict, the lift a volume can read, a queue of readable tests with read-out dates, the cost of one readable verdict. npx marketing-mindset sample|kill|verdict|unit|fit|queue|cost|mde|budget|brief|plan|warmup|aeo|jd|sections|read|install.",
   "keywords": [
     "agent-skill",
     "skill",
@@ -15,6 +15,7 @@
     "sample-size",
     "test-queue",
     "cost-per-verdict",
+    "channel-fit",
     "funnel-unit",
     "ab-test-verdict",
     "minimum-detectable-effect",