marketing-mindset 1.6.2 → 1.8.0

package/README.md

@@ -82,3 +82,35 @@ npx -y marketing-mindset 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
+
+## `brief` — the plan as markdown you can send
+
+```
+npx marketing-mindset brief --base 0.03 --lift 0.2 --cpl 4 --daily 500 --start 2026-09-21
+```
+
+One page: the floor in contacts per arm and in total, what reaching it costs at your price per contact,
+the dated read, a week-by-week table with the percentage of the floor covered, the three gates, and the
+kill rule. `--json` returns the same object for an agent or a script.
+
+Method, packages and the paid version of this work: https://axelfreeman.com/marketing-engineer.html
+
+## `mde` — what a volume you can afford can actually read
+
+The other direction of the same arithmetic: instead of the volume a lift requires, the lift a volume can
+read. Useful when the channel caps the volume (a small list, a niche audience, one store's traffic) and the
+honest question is not "how much do we need" but "what is the smallest win this test could ever show".
+
+```bash
+npx marketing-mindset mde --base 0.03 --per-arm 5000
+# base rate 3.00% · per arm 5,000 · power 0.8 · alpha 0.05
+# smallest readable relative lift: 33.4% (1pp absolute)
+# verdict: at this volume only a difference of 33.4% or more is readable ...
+
+npx marketing-mindset mde --base 0.03 --per-arm 5000 --json
+```
+
+`--per-arm` takes the volume you can actually buy per variant; `--power` (0.8 or 0.9) and `--alpha`
+(0.05, 0.01, 0.1) are the same knobs as `sample`. When no lift is readable at that volume the command
+says so instead of printing a number, and names the three ways out: more volume, a higher base rate, or a
+cheaper measurable unit (for cold email the reply rate, floor ~1,500–2,000 sends per variant).

package/bin/cli.js

@@ -3,6 +3,7 @@
  *   marketing-mindset                help + the test-size floors
  *   marketing-mindset sample         required per-arm sample size for a two-proportion test
  *   marketing-mindset kill           the kill rule for a running test
+ *   marketing-mindset mde            smallest relative lift a fixed per-arm volume can read
  *   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
@@ -380,6 +381,161 @@ function runPlan(opts) {
   return 0;
 }
 
+
+/* brief — the whole plan as one markdown page a client can keep: the floor, what reaching it costs,
+ * the dates, the gate for each week and the kill rule. --json returns the same object for an agent. */
+function mdeLift(rate, perArm, power, alpha) {
+  if (sampleSize(rate, 5, power, alpha) > perArm) { return null; }
+  let lo = 1e-6, hi = 5;
+  for (let i = 0; i < 100; i++) {
+    const mid = (lo + hi) / 2;
+    if (sampleSize(rate, mid, power, alpha) <= perArm) { hi = mid; } else { lo = mid; }
+  }
+  return hi;
+}
+
+function runMde(opts) {
+  const rate = Number(opts.base !== undefined ? opts.base : 0.03);
+  const perArm = Number(opts["per-arm"] !== undefined ? opts["per-arm"] : (opts.n !== undefined ? opts.n : 5000));
+  const power = Number(opts.power !== undefined ? opts.power : 0.8);
+  const alpha = Number(opts.alpha !== undefined ? opts.alpha : 0.05);
+  const problems = [];
+  if (!(rate > 0 && rate < 1)) { problems.push("base must be between 0 and 1 (0.03 = 3%)"); }
+  if (!(perArm > 0)) { problems.push("per-arm must be a positive volume (contacts, sends or visitors)"); }
+  if (!ZB[String(power)]) { problems.push("power must be 0.8 or 0.9 - this CLI carries exact quantiles for those two"); }
+  if (!ZA[String(alpha)]) { problems.push("alpha must be 0.05, 0.01 or 0.1"); }
+  if (problems.length) { console.error("mde: " + problems.join("; ")); return 1; }
+  const lift = mdeLift(rate, perArm, power, alpha);
+  if (lift === null) {
+    const out = {
+      base_rate: rate, per_arm: perArm, power, alpha,
+      min_relative_lift: null, min_absolute_pp: null, readable: false,
+      verdict: "no lift is readable at this volume: even a five-fold difference needs more than " + fmtNum(perArm) + " per arm at a " + (rate * 100).toFixed(2) + "% base rate. Raise the volume, raise the base rate (tighter list or sharper promise), or measure a cheaper unit (for cold email the readable unit is the reply rate, floor ~1,500-2,000 sends per variant)."
+    };
+    if (opts.json) { console.log(JSON.stringify(out, null, 2)); } else {
+      console.log("base rate " + (rate * 100).toFixed(2) + "% · per arm " + fmtNum(perArm) + " · power " + power + " · alpha " + alpha);
+      console.log("smallest readable relative lift: none");
+      console.log("verdict: " + out.verdict);
+    }
+    return 0;
+  }
+  const pct = Math.round(lift * 1000) / 10;
+  const pp = Math.round(rate * lift * 100 * 100) / 100;
+  const verdict = pct >= 20
+    ? "at this volume only a difference of " + pct + "% or more is readable - a smaller win will not separate from noise, so the honest plan is a bigger volume before the first read"
+    : "at this volume a difference of " + pct + "% or more is readable - a plan that promises less than that is promising a number this test cannot produce";
+  const out = {
+    base_rate: rate, per_arm: perArm, power, alpha,
+    min_relative_lift: Math.round(lift * 1e9) / 1e9,
+    min_absolute_pp: pp, readable: true, verdict
+  };
+  if (opts.json) { console.log(JSON.stringify(out, null, 2)); } else {
+    console.log("base rate " + (rate * 100).toFixed(2) + "% · per arm " + fmtNum(perArm) + " · power " + power + " · alpha " + alpha);
+    console.log("smallest readable relative lift: " + pct + "% (" + pp + "pp absolute)");
+    console.log("contacts needed at that lift: " + fmtNum(sampleSize(rate, lift, power, alpha)) + " per arm");
+    console.log("verdict: " + verdict);
+  }
+  return 0;
+}
+
+function fmtNum(n) {
+  return String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+function addDays(iso, n) {
+  const d = new Date(iso + "T00:00:00Z");
+  d.setUTCDate(d.getUTCDate() + n);
+  return d.toISOString().slice(0, 10);
+}
+function runBrief(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("brief: --base must be a rate between 0 and 1 (got: " + JSON.stringify(opts.base) + ")");
+    return 1;
+  }
+  if (!isFinite(lift) || lift <= 0) {
+    console.error("brief: --lift must be a positive relative lift, e.g. 0.2 for +20%");
+    return 1;
+  }
+  const cpl = Number(opts.cpl === undefined ? 0 : opts.cpl);
+  if (!isFinite(cpl) || cpl <= 0) {
+    console.error("brief: --cpl must be a positive cost per contact (got: " + JSON.stringify(opts.cpl) + ")");
+    return 1;
+  }
+  const daily = Number(opts.daily === undefined ? 0 : opts.daily);
+  if (opts.daily !== undefined && (!isFinite(daily) || daily <= 0)) {
+    console.error("brief: --daily must be a positive number of contacts per day");
+    return 1;
+  }
+  const weeks = opts.weeks === undefined ? 4 : Number(opts.weeks);
+  if (!isFinite(weeks) || weeks < 1 || weeks > 52 || Math.floor(weeks) !== weeks) {
+    console.error("brief: --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 perArm = sampleSize(base, lift, power, alpha);
+  const need = perArm * 2;
+  const cost = Math.round(need * cpl * 100) / 100;
+  const days = daily > 0 ? Math.ceil(need / daily) : null;
+  const readDate = days ? addDays(start, days - 1) : null;
+  const rows = [];
+  for (let w = 1; w <= weeks; w++) {
+    const planned = daily > 0 ? daily * 7 : 0;
+    const cumulative = planned * w;
+    rows.push({
+      week: w, start: addDays(start, (w - 1) * 7), end: addDays(start, w * 7 - 1),
+      planned_contacts: planned, cumulative,
+      against_floor_pct: Math.round(Math.min(100, (cumulative / need) * 100) * 10) / 10
+    });
+  }
+  const gates = [
+    "gate 1 (week 1): the tracked event fires on a real lead - if it does not, stop and fix the event, the channel stays closed",
+    "gate 2 (50% of floor): counts per arm look like the plan; if one arm is 30% behind, the split is broken, not the offer",
+    "gate 3 (read date): read the result at the declared floor or later, never earlier - below the floor the difference is noise"
+  ];
+  const killRule = "kill if conversions are at or under the floor on the read date; double only when the target rate is hit at or above the floor";
+  const result = {
+    base_rate: base, target_rate: Math.round(base * (1 + lift) * 10000) / 10000, relative_lift: lift,
+    power, alpha, cost_per_contact: cpl, per_arm: perArm, contacts_needed: need,
+    cost_to_read_the_test: cost, daily_contacts: daily > 0 ? daily : null,
+    days_to_read: days, first_honest_read: readDate, start_date: start, weeks: rows,
+    gates, kill_rule: killRule,
+    offer: "https://axelfreeman.com/marketing-engineer.html",
+    method: "two-proportion floor; same formula as `marketing-mindset sample`"
+  };
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+  const pct = (x) => (x * 100).toFixed(2);
+  console.log("# Campaign brief - the honest test plan\n");
+  console.log("Base rate " + pct(base) + "% -> target " + pct(base * (1 + lift)) + "% (relative lift +"
+    + (lift * 100).toFixed(0) + "%), power " + power + ", alpha " + alpha);
+  console.log("Floor: " + fmtNum(perArm) + " contacts per arm | " + fmtNum(need) + " in total");
+  console.log("At $" + cpl + " per contact: $" + fmtNum(cost) + " to read the test");
+  if (days) {
+    console.log("At " + fmtNum(daily) + " contacts/day: " + days + " days -> first honest read " + readDate);
+  } else {
+    console.log("Daily volume not given: add --daily to date the read");
+  }
+  console.log("\n## Weeks");
+  console.log("| Week | Dates | Contacts | Cumulative | % of floor |");
+  console.log("| --- | --- | --- | --- | --- |");
+  rows.forEach((r) => console.log("| " + r.week + " | " + r.start + " .. " + r.end + " | " + fmtNum(r.planned_contacts)
+    + " | " + fmtNum(r.cumulative) + " | " + r.against_floor_pct.toFixed(1) + "% |"));
+  console.log("\n## Gates");
+  gates.forEach((g) => console.log("- " + g));
+  console.log("\n## Kill rule");
+  console.log("- " + killRule);
+  console.log("\nMethod and packages: " + result.offer);
+  console.log("Tools: https://axelfreeman.github.io/marketing-mindset/tools/email-test-planner.html");
+  return 0;
+}
+
 const cmd = (process.argv[2] || "").toLowerCase();
 const rest = process.argv.slice(3);
 
@@ -414,8 +570,12 @@ if (cmd === "sample") {
   }, null, 2));
 } else if (cmd === "aeo") {
   process.exit(runAeo(flags(rest)));
+} else if (cmd === "brief") {
+  process.exit(runBrief(flags(rest)));
 } else if (cmd === "plan") {
   process.exit(runPlan(flags(rest)));
+} else if (cmd === "mde") {
+  process.exit(runMde(flags(rest)));
 } else if (cmd === "budget") {
   process.exit(runBudget(flags(rest)));
 } else if (cmd === "warmup") {
@@ -444,12 +604,14 @@ 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 brief           the whole plan as markdown you can send to a client
+      --base 0.03 --lift 0.2 --cpl 4 --daily 500 [--weeks 4] [--start 2026-09-21] [--json]
   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 mde             what a volume you can afford can actually read
+      --base 0.03 --per-arm 5000 [--power 0.8] [--alpha 0.05] [--json]
   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.6.2",
-  "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.",
+  "version": "1.8.0",
+  "description": "A marketer's operating mindset as an installable agent skill and CLI: test-size floors, kill rules, the lift a volume can actually read, agent-readiness checklist, marketing-engineer job description. npx marketing-mindset sample|kill|mde|budget|brief|plan|warmup|aeo|jd|sections|read|install.",
   "keywords": [
     "agent-skill",
     "skill",
@@ -13,6 +13,7 @@
     "llm",
     "prompt",
     "sample-size",
+    "minimum-detectable-effect",
     "job-description",
     "cold-email",
     "deliverability",