marketing-mindset 1.11.0 → 1.12.0

package/README.md

@@ -177,3 +177,26 @@ npx marketing-mindset cost --cost 0.02 --daily 500 --budget 5000
 assumed. The floor uses the same formula as `sample`, so a budget planned here, a queue planned with `queue` and a
 test read with `verdict` stay consistent. Two things it refuses to hide: stopping before the floor buys a sample
 rather than a result, and money buys tests while volume limits how many can run at once.
+
+## `unit` — which step of your funnel can fund a verdict
+
+A funnel is a list of counted events per month. `unit` answers the only question that decides whether a
+channel can be judged: which of those steps happens often enough to reach a test floor, and how many
+months it needs.
+
+```bash
+npx marketing-mindset unit --steps visits:12000,signups:900,activations:270,paid:40
+```
+```
+unit visits -> signups: rate 7.50%, floor 5,280 per arm, 6,000 events per arm a month -> 1 month(s) to read
+unit signups -> activations: rate 30.00%, floor 963 per arm, 450 events per arm a month -> 3 month(s) to read
+unit activations -> paid: rate 14.81%, floor 2,438 per arm, 135 events per arm a month -> 19 month(s) to read
+readable at this volume: visits -> signups in 1 month(s)
+```
+
+`--json` returns the same object: one entry per consecutive pair with `rate`, `floor_per_arm`,
+`arm_events_per_month` and `months_to_read`, plus `readable_unit`, `unreadable_units` and three gates.
+The floor comes from the same formula as `sample`, and the arms split the earlier step's volume in half,
+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.

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 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
  *   marketing-mindset install        copy the skill into your agent's skills directory
@@ -625,6 +626,110 @@ function runCost(opts) {
   return 0;
 }
 
+var UN_ZA = { "0.05": 1.9599639845, "0.01": 2.5758293036, "0.1": 1.6448536270 };
+var UN_ZB = { "0.8": 0.8416212336, "0.9": 1.2815515655 };
+function unRound6(x) { return Math.round(x * 1000000) / 1000000; }
+function unSampleSize(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 = UN_ZA[String(alpha)] || UN_ZA["0.05"];
+  const zb = UN_ZB[String(power)] || UN_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 planUnits(input) {
+  const steps = input.steps || [];
+  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 (steps.length < 2) { problems.push("steps: pass at least two steps, e.g. visits:12000,signups:900"); }
+  steps.forEach(function (s) {
+    if (!s || !s.name) { problems.push("steps: every step needs a name"); }
+    if (!(Number(s.count) > 0)) { problems.push("steps: count for '" + ((s && s.name) || "?") + "' must be a positive number of events per month"); }
+  });
+  if (!(lift > 0) || !(lift < 5)) { problems.push("lift worth detecting: a fraction, 0.2 = +20% relative"); }
+  if (!UN_ZB[String(power)]) { problems.push("power must be 0.8 or 0.9"); }
+  if (!UN_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 units = [];
+  for (let i = 0; i < steps.length - 1; i++) {
+    const a = steps[i], b = steps[i + 1];
+    const rate = Number(b.count) / Number(a.count);
+    const per_arm = unSampleSize(rate, lift, power, alpha);
+    const arm_events_per_month = Number(a.count) / 2;
+    const months = Math.ceil(per_arm / arm_events_per_month);
+    units.push({
+      unit: a.name + " -> " + b.name, from: a.name, to: b.name, rate: unRound6(rate),
+      floor_per_arm: per_arm, months_to_read: months,
+      arm_events_per_month: arm_events_per_month
+    });
+  }
+  let chosen = null;
+  units.forEach(function (u) { if (!chosen && u.months_to_read <= horizon) { chosen = u; } });
+  const unreadable = units.filter(function (u) { return u.months_to_read > horizon; }).map(function (u) { return u.unit; });
+  const last = units[units.length - 1];
+  const gates = [
+    "the earliest step is the cheapest to read and the least able to own the outcome: " + units[0].unit +
+      " reads in " + units[0].months_to_read + " month(s), which is why it is usually the number already in the dashboard",
+    "the money step has no next step at this volume: " + last.unit + " is the last pair in this funnel, so money always reads one step behind the unit you chose",
+    chosen
+      ? "readable at this volume: " + chosen.unit + " in " + chosen.months_to_read + " month(s) - fund that one test and set the read-out date before it starts"
+      : "nothing in this funnel is readable within " + horizon + " month(s): pick a more frequent unit or write down that the month produces a progress report"
+  ];
+  return {
+    steps: steps.length, lift: lift, power: power, alpha: alpha, horizon_months: horizon,
+    units: units,
+    readable_unit: chosen ? chosen.unit : "",
+    readable_months: chosen ? chosen.months_to_read : 0,
+    unreadable_units: unreadable,
+    gates: gates
+  };
+}
+
+function runUnit(opts) {
+  const spec = opts.steps;
+  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 steps = [];
+  if (typeof spec !== "string" || spec.length === 0) {
+    problems.push("steps: pass --steps visits:12000,signups:900,activations:270,paid:40");
+  } else {
+    spec.split(",").forEach(function (part) {
+      const bits = part.split(":");
+      if (bits.length !== 2 || !bits[0] || !(Number(bits[1]) > 0)) {
+        problems.push("steps: '" + part.trim() + "' must look like name:events_per_month");
+      } else {
+        steps.push({ name: bits[0].trim(), count: Number(bits[1]) });
+      }
+    });
+  }
+  if (problems.length) { console.error("unit: " + problems.join("; ")); return 1; }
+  const out = planUnits({ steps: steps, lift: lift, power: power, alpha: alpha, horizon: horizon });
+  if (out.problems) { console.error("unit: " + out.problems.join("; ")); return 1; }
+  if (opts.json) { console.log(JSON.stringify(out, null, 2)); } else {
+    out.units.forEach(function (u) {
+      console.log("unit " + u.unit + ": rate " + (u.rate * 100).toFixed(2) + "%, floor " + fmtNum(u.floor_per_arm) +
+        " per arm, " + fmtNum(u.arm_events_per_month) + " events per arm a month -> " + u.months_to_read + " month(s) to read");
+    });
+    if (out.readable_unit) {
+      console.log("readable at this volume: " + out.readable_unit + " in " + out.readable_months + " month(s)");
+    } else {
+      console.log("readable at this volume: nothing within " + horizon + " month(s)");
+    }
+    if (out.unreadable_units.length) { console.log("out of reach: " + out.unreadable_units.join(", ")); }
+    out.gates.forEach(function (g) { console.log("gate: " + g); });
+  }
+  return 0;
+}
+
 function fmtNum(n) {
   return String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
 }
@@ -759,6 +864,8 @@ if (cmd === "sample") {
   process.exit(runVerdict(flags(rest)));
 } else if (cmd === "queue") {
   process.exit(runQueue(flags(rest)));
+} else if (cmd === "unit") {
+  process.exit(runUnit(flags(rest)));
 } else if (cmd === "cost") {
   process.exit(runCost(flags(rest)));
 } else if (cmd === "aeo") {
@@ -806,6 +913,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 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]
       --daily 500 --days 90 --start 2026-09-21 [--base 0.03] [--lift 0.2] [--power 0.8] [--alpha 0.05]
       --a 120/4000 --b 168/4000 [--alpha 0.05] [--json]

package/package.json

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