marketing-mindset 1.4.0 → 1.6.0

package/README.md

@@ -67,3 +67,18 @@ npx -y marketing-mindset@1.4.0 warmup --start 2026-09-21 --target 200 --days 21
 ```
 
 Day-by-day ramp for a new sending domain: starts at 20/day (or the target, if smaller), grows by half a day, never above the target, and prints the four stop rules (bounce >2%/day, complaints >0.1%, any reply ends that sequence, opens halving with flat sends -> drop back two ramp days). `--json` gives the machine-readable schedule. Work with me: https://axelfreeman.com/marketing-engineer.html
+
+### Test budget: `budget`
+
+```
+npx -y marketing-mindset@1.5.0 budget --base 0.03 --lift 0.2 --cpl 4 --daily 500
+```
+
+The money side of the same floor `sample` computes: contacts needed in both arms, cost per arm and cost to read the test at your cost per contact, days to the floor at a given daily volume, and the spend guard (below the floor the difference is noise, not a result). `--json` for agents. Work with me: https://axelfreeman.com/marketing-engineer.html
+### Dated plan: `plan`
+
+```
+npx -y marketing-mindset@1.6.0 plan --base 0.03 --lift 0.2 --daily 500 --weeks 4
+```
+
+The floor from `sample`/`budget` laid out on a calendar: contacts per week, cumulative volume against the floor, the first date the test can honestly be read, the mechanics-only first week, and an honest verdict when the volume cannot reach the floor inside the plan. `--json` for agents. Work with me: https://axelfreeman.com/marketing-engineer.html

package/bin/cli.js

@@ -233,6 +233,153 @@ function runWarmup(opts) {
   return 0;
 }
 
+/* budget — the money it takes to read a test, from the same sample-size floor as `sample`. */
+function runBudget(opts) {
+  const base = Number(opts.base === undefined ? 0 : opts.base);
+  const lift = Number(opts.lift === undefined ? 0 : opts.lift);
+  if (!isFinite(base) || base <= 0 || base >= 1) {
+    console.error("budget: --base must be a rate between 0 and 1 (got: " + JSON.stringify(opts.base) + ")");
+    return 1;
+  }
+  if (!isFinite(lift) || lift <= 0) {
+    console.error("budget: --lift must be a positive relative lift, e.g. 0.2 for +20% (got: " + JSON.stringify(opts.lift) + ")");
+    return 1;
+  }
+  const cpl = Number(opts.cpl === undefined ? 0 : opts.cpl);
+  if (!isFinite(cpl) || cpl <= 0) {
+    console.error("budget: --cpl must be a positive cost per contact (got: " + JSON.stringify(opts.cpl) + ")");
+    return 1;
+  }
+  const power = opts.power === undefined ? 0.8 : opts.power;
+  const alpha = opts.alpha === undefined ? 0.05 : opts.alpha;
+  const daily = opts.daily === undefined ? 0 : Number(opts.daily);
+  if (opts.daily !== undefined && (!isFinite(daily) || daily <= 0)) {
+    console.error("budget: --daily must be a positive number of contacts per day");
+    return 1;
+  }
+  const perArm = sampleSize(base, lift, power, alpha);
+  const bothArms = perArm * 2;
+  const perArmCost = Math.round(perArm * cpl * 100) / 100;
+  const totalCost = Math.round(bothArms * cpl * 100) / 100;
+  const days = daily > 0 ? Math.ceil(bothArms / daily) : null;
+  const p2 = base * (1 + lift);
+  const expectedLift = Math.round((p2 - base) * 10000) / 10000;
+  if (opts.json) {
+    console.log(JSON.stringify({
+      base_rate: base, target_rate: Math.round(p2 * 10000) / 10000, relative_lift: lift, power: power, alpha: alpha,
+      per_arm: perArm, contacts_needed: bothArms, cost_per_contact: cpl,
+      cost_per_arm: perArmCost, cost_to_read_the_test: totalCost,
+      daily_contacts: daily > 0 ? daily : null, days_to_read: days,
+      spend_guard: [
+        "below the per-arm floor the difference is noise, not a result - that spend is a donation",
+        "decide the kill rule before the first send: what result ends the test and what result doubles it",
+        "if cost_to_read_the_test is more than the deal is worth, change the base rate or the channel, not the sample"
+      ],
+      method: "two-proportion sample size; same formula as `marketing-mindset sample`"
+    }, null, 2));
+    return 0;
+  }
+  console.log("Honest test budget: base " + (base * 100).toFixed(2) + "% -> target " + (p2 * 100).toFixed(2)
+    + "% (relative lift " + lift + "), power " + power + ", alpha " + alpha);
+  console.log("Per arm: " + perArm + " contacts  |  both arms: " + bothArms + " contacts");
+  console.log("At $" + cpl + " per contact: $" + perArmCost + " per arm, $" + totalCost + " to read the test");
+  if (days) console.log("At " + daily + " contacts/day: " + days + " days to reach the floor");
+  console.log("Spend guard: under the floor the difference is noise, not a result - that spend is a donation.");
+  console.log("Kill rule first: what result ends the test, what result doubles it.");
+  console.log("Method and packages: https://axelfreeman.com/marketing-engineer.html");
+  return 0;
+}
+
+
+/* plan — the same floor as `sample`/`budget`, laid out on a calendar: weekly volume, the date the
+ * test can first be read, the mechanics-only week, and an honest verdict when it does not fit. */
+function runPlan(opts) {
+  const base = Number(opts.base === undefined ? 0 : opts.base);
+  const lift = Number(opts.lift === undefined ? 0 : opts.lift);
+  if (!isFinite(base) || base <= 0 || base >= 1) {
+    console.error("plan: --base must be a rate between 0 and 1 (got: " + JSON.stringify(opts.base) + ")");
+    return 1;
+  }
+  if (!isFinite(lift) || lift <= 0) {
+    console.error("plan: --lift must be a positive relative lift, e.g. 0.2 for +20%");
+    return 1;
+  }
+  const daily = Number(opts.daily === undefined ? 0 : opts.daily);
+  if (!isFinite(daily) || daily <= 0) {
+    console.error("plan: --daily must be a positive number of contacts per day (got: " + JSON.stringify(opts.daily) + ")");
+    return 1;
+  }
+  const weeks = opts.weeks === undefined ? 4 : Number(opts.weeks);
+  if (!isFinite(weeks) || weeks < 1 || weeks > 52 || Math.floor(weeks) !== weeks) {
+    console.error("plan: --weeks must be a whole number between 1 and 52");
+    return 1;
+  }
+  const power = opts.power === undefined ? 0.8 : opts.power;
+  const alpha = opts.alpha === undefined ? 0.05 : opts.alpha;
+  const start = typeof opts.start === "string" && /^\d{4}-\d{2}-\d{2}$/.test(opts.start)
+    ? opts.start : new Date().toISOString().slice(0, 10);
+  const t0 = Date.parse(start + "T00:00:00Z");
+  const day = (n) => new Date(t0 + n * 86400000).toISOString().slice(0, 10);
+
+  const perArm = sampleSize(base, lift, power, alpha);
+  const need = perArm * 2;
+  const daysToRead = Math.ceil(need / daily);
+  const weekRows = [];
+  for (let w = 1; w <= weeks; w++) {
+    const confirmed = Math.min(daily * 7 * w, need);
+    weekRows.push({
+      week: w,
+      start: day((w - 1) * 7),
+      end: day(w * 7 - 1),
+      planned_contacts: daily * 7,
+      cumulative: daily * 7 * w,
+      against_floor_pct: Math.round(Math.min(100, (daily * 7 * w / need) * 1000) / 10)
+    });
+  }
+  const capacity = daily * 7 * weeks;
+  const readable = capacity >= need;
+  const p2 = base * (1 + lift);
+  const out = {
+    start_date: start,
+    base_rate: base, target_rate: Math.round(p2 * 10000) / 10000, relative_lift: lift,
+    power: power, alpha: alpha,
+    per_arm: perArm, contacts_needed: need, daily_contacts: daily, weeks_planned: weeks,
+    weekly_volume: daily * 7, planned_capacity: capacity,
+    capacity_vs_floor_pct: Math.round((capacity / need) * 1000) / 10,
+    days_to_read: daysToRead,
+    read_date: day(daysToRead - 1),
+    readable_within_plan: readable,
+    plan: weekRows,
+    gates: [
+      "Week 1 is mechanics only: delivery, bounces, replies per 100 sent. Do not read a conversion rate.",
+      "First honest read: " + day(daysToRead - 1) + " - before that date a difference between variants is noise.",
+      "Every week: if the delivered volume is under half of the planned volume, fix the channel first; the test is not running."
+    ],
+    kill_rule: "What result ends the test and what result doubles it is decided before the first send, in writing.",
+    verdict: readable
+      ? "Readable in " + weeks + " week(s): the floor lands on " + day(daysToRead - 1) + " at " + daily + " contacts/day."
+      : "Not readable in " + weeks + " week(s): " + capacity + " contacts planned against a floor of " + need +
+        ". At " + daily + " contacts/day it needs " + daysToRead + " days - extend the plan, raise the volume, or change the offer.",
+    method: "two-proportion sample size; same formula as `marketing-mindset sample`"
+  };
+  if (opts.json) {
+    console.log(JSON.stringify(out, null, 2));
+    return 0;
+  }
+  console.log("Plan from " + out.start_date + ": base " + (base * 100).toFixed(2) + "% -> " +
+    (p2 * 100).toFixed(2) + "% (lift " + lift + "), " + daily + " contacts/day, " + weeks + " week(s)");
+  console.log("Floor: " + perArm + " per arm, " + need + " contacts in total. Weekly volume: " + daily * 7 + ".");
+  weekRows.forEach((w) => {
+    console.log("  Week " + w + " (" + w.start + " .. " + w.end + "): " + w.planned_contacts +
+      " contacts, cumulative " + w.cumulative + " (" + w.against_floor_pct + "% of the floor)");
+  });
+  console.log("First honest read: " + out.read_date + " (day " + daysToRead + ").");
+  console.log(out.verdict);
+  out.gates.forEach((g) => console.log("  gate: " + g));
+  console.log("Packages and the walkthrough: https://axelfreeman.com/marketing-engineer.html");
+  return 0;
+}
+
 const cmd = (process.argv[2] || "").toLowerCase();
 const rest = process.argv.slice(3);
 
@@ -267,6 +414,10 @@ if (cmd === "sample") {
   }, null, 2));
 } else if (cmd === "aeo") {
   process.exit(runAeo(flags(rest)));
+} else if (cmd === "plan") {
+  process.exit(runPlan(flags(rest)));
+} else if (cmd === "budget") {
+  process.exit(runBudget(flags(rest)));
 } else if (cmd === "warmup") {
   process.exit(runWarmup(flags(rest)));
 } else if (cmd === "jd") {
@@ -293,6 +444,12 @@ Usage:
       --base 0.03 --lift 0.2 --power 0.8 --alpha 0.05
   npx marketing-mindset kill            kill rule for a running test
       --base 0.03 --n 1500 --lift 0.2
+  npx marketing-mindset budget          what an honest test costs before you can read it
+      --base 0.03 --lift 0.2 --cpl 4 [--daily 500]
+  npx marketing-mindset plan            dated plan: weekly volume, gates, first honest read
+      --base 0.03 --lift 0.2 --daily 500 [--weeks 4] [--start 2026-09-21]
+  npx marketing-mindset plan            dated plan: weekly volume, gates, first honest read
+      --base 0.03 --lift 0.2 --daily 500 [--weeks 4] [--start 2026-09-21]
   npx marketing-mindset warmup          day-by-day sending ramp with stop rules
       --start 2026-09-21 --target 200 --days 21 --mailboxes 4
   npx marketing-mindset jd              marketing engineer job description

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "marketing-mindset",
-  "version": "1.4.0",
-  "description": "A marketer's operating mindset as an installable agent skill and CLI: test-size floors, kill rules, agent-readiness checklist, marketing-engineer job description. npx marketing-mindset sample|kill|warmup|aeo|jd|sections|read|install.",
+  "version": "1.6.0",
+  "description": "A marketer's operating mindset as an installable agent skill and CLI: test-size floors, kill rules, agent-readiness checklist, marketing-engineer job description. npx marketing-mindset sample|kill|budget|warmup|aeo|jd|sections|read|install.",
   "keywords": [
     "agent-skill",
     "skill",
@@ -16,7 +16,10 @@
     "job-description",
     "cold-email",
     "deliverability",
-    "warmup"
+    "warmup",
+    "budget",
+    "cac",
+    "unit-economics"
   ],
   "license": "MIT",
   "author": "Axel Freeman",