marketing-mindset-mcp 1.0.1 → 1.0.3

package/README.md

@@ -33,6 +33,9 @@ Client config (generic stdio server):
 | `read_section` | one section by fuzzy title match (`"numbers lie"`, `"competitors"`, `"hypotheses"`) |
 | `sample_size` | per-arm volume a two-proportion test needs before a verdict is readable |
 | `kill_rule` | expected conversions, the kill floor, and whether the test has enough volume to read yet |
+| `aeo_check` | agent-readiness / AEO audit: the 23 weighted checks that decide whether AI answers can find, read and quote a site; pass the numbers you pass to get a weighted score |
+| `jd` | a marketing-engineer job description about artifacts and numbers: what the role owns, what must exist by day 90, how it is measured, screening questions |
+| `playbook` | whether writing a playbook is the right move right now: pass how many proven, repeatable moves you have and it returns `search` / `draining` / `delegate`, the next move, and the rules (one proven move, one line; ~6 hypotheses before you can hire marketing; failed hypotheses archived in one line, never handed to the next person) |
 
 `sample_size` and `kill_rule` implement the same two-proportion arithmetic as the free
 [test-size calculator](https://axelfreeman.github.io/marketing-mindset/tools/email-test-planner.html).
@@ -44,6 +47,19 @@ tools/call sample_size {"baseline_rate": 0.03, "min_relative_lift": 0.2}
 -> per_arm 13914   (i.e. ~13.9k sends per variant before any verdict)
 ```
 
+
+## Example: the AEO audit
+
+```
+tools/call aeo_check {}
+-> 23 checks, max score 55, grouped into crawlability, answer-ready content, machine-readable, someone else's page, proof and measurement
+
+tools/call aeo_check {"checked": [1,2,4,6,8,11,12,16,20,21,22]}
+-> score, band and the highest-weight gaps
+```
+
+The same checklist is a free page: [agent-readiness checklist](https://axelfreeman.github.io/marketing-mindset/tools/aeo-readiness-checklist.html). The JD tool has a web version too: [JD generator](https://axelfreeman.github.io/marketing-mindset/tools/marketing-engineer-jd-generator.html).
+
 ## License
 
 MIT.

package/bin/server.js

@@ -9,7 +9,7 @@ const fs = require("fs");
 const path = require("path");
 
 const SKILL_PATH = path.join(__dirname, "..", "skill", "SKILL.md");
-const SERVER = { name: "marketing-mindset-mcp", version: "1.0.0" };
+const SERVER = { name: "marketing-mindset-mcp", version: "1.0.3" };
 const PROTOCOL = "2024-11-05";
 
 function skillText() {
@@ -63,16 +63,116 @@ function killRule(rate, n, lift) {
   const floor = Math.max(0, Math.floor(bound));
   const expected = rate * n;
   const target = rate * (1 + lift) * n;
-  let verdict = "keep running — not enough volume to read the result";
+  let verdict = "keep running - not enough volume to read the result";
   if (n < sampleSize(rate, lift, 0.8, 0.975)) {
-    verdict = "keep running — below the required volume for this effect size, a verdict now is noise";
+    verdict = "keep running - below the required volume for this effect size, a verdict now is noise";
   } else {
-    verdict = "read it — volume is sufficient; kill if conversions are at or under the floor";
+    verdict = "read it - volume is sufficient; kill if conversions are at or under the floor";
   }
   return { expected_conversions: Math.round(expected * 10) / 10, kill_floor: floor,
            target_conversions: Math.round(target * 10) / 10, verdict };
 }
 
+/* --- agent readiness / AEO checklist: 5 groups, 23 checks, 55 points ------------------------ */
+const AEO_GROUPS = [["Crawlability",[["robots.txt does not block GPTBot, ClaudeBot, PerplexityBot, Google-Extended, OAI-SearchBot",3],["Pages render without JavaScript, or have a server-side/no-JS fallback",2],["No login wall or consent interstitial in front of the content you want quoted",3],["The page returns 200 to a plain curl with no cookies",2],["One canonical URL per answer - no www/non-www or trailing-slash duplicates",2]]],["Answer-ready content",[["Every important page answers one question in the first 60 words",3],["Headings are questions a human would type, not internal project names",2],["Prices, limits and timeframes are stated as numbers, not 'flexible'",3],["Claims have a source or a live URL attached",2],["A definition page exists for the category you want to be cited in",3]]],["Machine-readable",[["schema.org markup on service/product pages (Service, Offer, Product, FAQPage)",3],["FAQPage or QAPage markup on question pages, answers 40-500 words",2],["XML sitemap submitted, and every new URL pinged via IndexNow",2],["llms.txt describes what the site answers and where the canonical pages are",2],["Organisation/Person entity links the page to a real, verifiable identity",2]]],["Someone else's page",[["You are present where the model already reads: package registries, repos, docs",3],["At least one open, mergeable pull request or discussion contribution",2],["Your content is mirrored somewhere you do not control",2],["A third-party page links to your canonical URL",3]]],["Proof and measurement",[["Every claim on the site can be opened by the reader in one click",3],["One tracked event for the outcome that matters, in your own analytics property",3],["A public changelog or artifact list with dates",2],["An archived snapshot of the key pages exists",1]]]];
+const AEO_MAX = AEO_GROUPS.reduce((a, g) => a + g[1].reduce((b, c) => b + c[1], 0), 0);
+
+function aeoFlat() {
+  const out = [];
+  AEO_GROUPS.forEach(([group, items]) => items.forEach(([text, weight]) => out.push({ group, check: text, weight })));
+  return out;
+}
+
+function aeoCheck(checked) {
+  const flat = aeoFlat();
+  const base = { check_count: flat.length, max_score: AEO_MAX,
+                 groups: AEO_GROUPS.map(([g, its]) => ({ group: g, checks: its.map(([t, w]) => ({ check: t, weight: w })) })),
+                 score_guide: "<30% invisible for structural reasons; 30-60% crawlable but not quotable; 60-80% quoted occasionally (third-party presence missing); >80% the rest is cadence" };
+  if (!Array.isArray(checked)) return Object.assign({}, base, { mode: "checklist" });
+  const idx = checked.map((v) => Number(v)).filter((n) => Number.isInteger(n) && n >= 1 && n <= flat.length);
+  const passed = new Set(idx);
+  const score = flat.reduce((a, c, i) => a + (passed.has(i + 1) ? c.weight : 0), 0);
+  const pct = Math.round((score / AEO_MAX) * 1000) / 10;
+  const missing = flat.map((c, i) => ({ n: i + 1, check: c.check, group: c.group, weight: c.weight }))
+    .filter((c) => !passed.has(c.n)).sort((a, b) => b.weight - a.weight).slice(0, 3);
+  return { mode: "score", passed: passed.size, of_checks: flat.length, score, max_score: AEO_MAX,
+           percent: pct,
+           band: pct < 30 ? "invisible for structural reasons" : pct < 60 ? "crawlable but not quotable"
+             : pct < 80 ? "quoted occasionally - third-party presence is the gap" : "the rest is cadence",
+           highest_weight_unchecked: missing,
+           note: "Weighted, not a checklist of equals. Two checks carry the most weight: one question answered in the first 60 words, and prices/limits stated as numbers." };
+}
+
+/* --- marketing engineer JD generator (same text as the npm CLI `jd` and the free web tool) --- */
+const JD_SURFACES = {
+  seo: "search and answer engines (pages written to be quoted, schema, llms.txt)",
+  out: "outbound and lifecycle email (list, sequence, deliverability, suppression)",
+  paid: "paid acquisition (structure, creative, spend gates)",
+  auto: "automation and tracking (routing, events, failure alerts)",
+  analytics: "measurement (one event that matters, sample-size floors, kill rules)",
+  ai: "agent skills and AI-assisted production (reusable operating files, not one-off prompts)",
+};
+const JD_OFFER = "https://axelfreeman.com/marketing-engineer.html";
+const JD_COST = "https://axelfreeman.com/marketing-engineer-cost.html";
+const JD_TOOL = "https://axelfreeman.github.io/marketing-mindset/tools/marketing-engineer-jd-generator.html";
+
+function jdText(o) {
+  const dflt = (v, d) => (v === undefined || v === null || v === "" || v === true) ? d : String(v);
+  const level = dflt(o.level, "senior");
+  const mode = dflt(o.mode, level === "contract" ? "contract" : "fulltime");
+  const sv = dflt(o.surfaces, null);
+  const keys = sv ? sv.split(",").map((s) => s.trim()).filter((s) => JD_SURFACES[s]) : Object.keys(JD_SURFACES);
+  const surf = keys.length ? keys : Object.keys(JD_SURFACES);
+  const company = dflt(o.company, "[company, product, what you sell in one line]");
+  const bottleneck = dflt(o.bottleneck, "[the bottleneck you are hiring against]");
+  const ninety = mode === "contract"
+    ? "A 6-week engagement with one written kill rule, then a decision"
+    : level === "lead"
+      ? "A documented system: which paths exist, what each one costs, what gets killed next quarter"
+      : "A path live in production with its event recording, or a written note saying why it was killed";
+  const L = [];
+  L.push("# Marketing Engineer (" + level + ", " + mode + ")", "");
+  L.push("## The company and the job");
+  L.push(company + ".", "");
+  L.push("We are hiring a marketing engineer because: " + bottleneck + ".", "");
+  L.push("You will not be handed a channel to run and a deck to fill in. You will be handed a broken or "
+       + "unmeasured path and be expected to make it work, show the number, and write the rule that decides "
+       + "whether it lives.", "");
+  L.push("## What the role owns");
+  surf.forEach((k, i) => L.push((i + 1) + ". " + JD_SURFACES[k]));
+  L.push("", "## What must exist by day 90");
+  L.push("1. One path live in production: entry point, sequence or flow, and the event that fires on a conversion.");
+  L.push("2. A written declaration of the sample size each running test needs before a result counts as a result.");
+  L.push("3. A kill rule per test, written before the test starts: at what volume and what result we stop.");
+  L.push("4. One dashboard we can open without asking you for an export.");
+  L.push("5. " + ninety + ".");
+  L.push("", "## How we will measure you");
+  L.push("- Cost per qualified conversation or per activated account, when the volume is above the declared floor.");
+  L.push("- Live, openable artifacts still running 30 days after you last touched them.");
+  L.push("- Whether a decision made last month can be re-checked today from the data, without you in the room.");
+  L.push("- We do not count posts published, prompts written, or hours logged.");
+  L.push("", "## Requirements");
+  L.push("- You have shipped something that is still running: a page, a sequence, a script, an integration. Links beat adjectives.");
+  L.push("- You can explain, in one paragraph, why a 4-of-100 result is not a win.");
+  L.push("- You work in the tooling yourself: HTML/CSS, a spreadsheet, analytics, basic scripting, or an agent that writes them for you.");
+  L.push("- You write plainly; internal names and jargon are not allowed in anything a customer reads.");
+  L.push("", "## Nice to have");
+  L.push("- Experience writing pages that answer engines quote (schema, FAQ markup, plain HTML).");
+  L.push("- A history of killing your own work in public, with the numbers attached.");
+  L.push("", "## Not this role");
+  L.push("- Meeting-led account management, community management, brand campaigns, reporting for its own sake.");
+  L.push("", "## Screening questions (ask these first)");
+  L.push("1. Send us one link to something you built that is still live.");
+  L.push("2. We ran 40 sends, got 4 replies, variant B looks better. What do you do next?");
+  L.push("3. How many sends does a two-variant email test need before the result means anything? "
+       + "(Expected: ~1,500-2,000 per arm at a 3% baseline, 80% power, 20% relative lift.)");
+  L.push("4. Name one thing you killed and what the number was.");
+  L.push("5. What will you build in the first two weeks here, and how will we see it?");
+  L.push("", "--", "Generated by marketing-mindset (npm). Method and pricing: " + JD_OFFER
+       + "  |  Packages: " + JD_COST + "  |  Web version of this tool: " + JD_TOOL);
+  return L.join("\n");
+}
+
 const TOOLS = [
   {
     name: "list_sections",
@@ -107,17 +207,48 @@ const TOOLS = [
         min_relative_lift: { type: "number", description: "Smallest relative lift worth detecting" }
       },
       required: ["baseline_rate", "n", "min_relative_lift"], additionalProperties: false }
+  },
+  {
+    name: "aeo_check",
+    description: "Agent-readiness / AEO audit: the 23 weighted checks that decide whether AI answers can find, read and quote a site. Call with no arguments for the checklist; pass the 1-based numbers of the checks the site passes (e.g. {\"checked\":[1,2,4,6,8,11,12]}) to get the weighted score, the band and the highest-weight gaps.",
+    inputSchema: { type: "object",
+      properties: { checked: { type: "array", items: { type: "integer" },
+                              description: "Optional: 1-based numbers of checks the site passes, out of 23" } },
+      additionalProperties: false }
+  },
+  {
+    name: "jd",
+    description: "Generates a marketing-engineer job description that is about artifacts and numbers instead of adjectives: what the role owns, what must exist by day 90, how it is measured, and the screening questions (including the sample-size question with the expected answer).",
+    inputSchema: { type: "object",
+      properties: {
+        level: { type: "string", description: "senior (default), lead, or contract" },
+        mode: { type: "string", description: "fulltime (default) or contract" },
+        surfaces: { type: "string", description: "Comma-separated subset of: seo, out, paid, auto, analytics, ai. Default: all." },
+        company: { type: "string", description: "One line about the company/product" },
+        bottleneck: { type: "string", description: "The bottleneck you are hiring against" }
+      },
+      additionalProperties: false }
+  },
+  {
+    name: "playbook",
+    description: "Decides whether writing a marketing playbook is the right move right now. A playbook is the second step, never the first: it records proven, repeatable client-acquisition moves (one move, one line) and exists to drain a working hypothesis to the bottom — not to discover one. Pass how many proven repeatable moves you actually have; returns the stage (search / draining / delegate), the next move, and the rules that go with it.",
+    inputSchema: { type: "object",
+      properties: {
+        proven_hypotheses: { type: "integer", description: "Proven, repeatable client-acquisition moves you actually have (0 if none)" },
+        written_down: { type: "boolean", description: "Whether those working moves are already written down as instructions" }
+      },
+      required: ["proven_hypotheses"], additionalProperties: false }
   }
 ];
 
 function callTool(name, args) {
   args = args || {};
   if (name === "list_sections") {
-    return headingList().map((h) => `${"#".repeat(h.level)} ${h.title}`).join("\n");
+    return headingList().map((h) => "#".repeat(h.level) + " " + h.title).join("\n");
   }
   if (name === "read_section") {
     const s = readSection(args.section);
-    if (!s) return `No section matching "${args.section}". Call list_sections for the index.`;
+    if (!s) return 'No section matching "' + args.section + '". Call list_sections for the index.';
     return s.text;
   }
   if (name === "sample_size") {
@@ -140,6 +271,47 @@ function callTool(name, args) {
     out.volume_in_test = n;
     return JSON.stringify(out, null, 2);
   }
+  if (name === "aeo_check") {
+    return JSON.stringify(aeoCheck(args.checked), null, 2);
+  }
+  if (name === "jd") {
+    return jdText(args);
+  }
+  if (name === "playbook") {
+    const proven = Number(args.proven_hypotheses || 0);
+    if (!(proven >= 0)) throw new Error("proven_hypotheses must be a count of proven, repeatable moves (0 if none)");
+    const CRITICAL = 6;
+    let stage, verdict, next;
+    if (proven === 0) {
+      stage = "search";
+      verdict = "No playbook yet — there is no proven move to write down. A playbook built at this point is a notebook of guesses, and the most expensive way to feel productive.";
+      next = "Find client #1 by hand (cold outreach, free) and get one move that actually returns clients. The playbook is the output of that search, not the input to it.";
+    } else if (proven < CRITICAL) {
+      stage = "draining";
+      verdict = "You have " + proven + " proven move(s): write them down and press each to its ceiling. That is what a playbook is for — draining a working hypothesis, not discovering one.";
+      next = "Keep hunting until roughly " + CRITICAL + " proven moves. Below that there is not enough to hand over to a hire.";
+    } else {
+      stage = "delegate";
+      verdict = "Critical mass reached (" + proven + " >= " + CRITICAL + "): there is something real to hand over — you can hire marketing.";
+      next = "Handing it over ends free search and starts regular management: goals, volume, cadence, reporting. Draining a hypothesis to the bottom is an operating task, not an exploration one.";
+    }
+    return [
+      "proven, repeatable moves: " + proven + " · critical mass " + CRITICAL,
+      "stage: " + stage,
+      "written down: " + (args.written_down ? "yes" : "no"),
+      "verdict: " + verdict,
+      "next: " + next,
+      "",
+      "Rules:",
+      "- The playbook records proven, repeatable client-acquisition moves only — one proven move, one line.",
+      "- It is the second step: find a working hypothesis by hand -> press it to its ceiling -> only then write it down.",
+      "- Filled from your own experiments on your own base. Borrowed case studies are a wish list, not a playbook.",
+      "- Delegation (a hire, a department, an agent) changes the mode: free search ends, regular management begins.",
+      "- Failed hypotheses go to the archive in one line — never analysed, never handed to a new person. A marketer starts from zero, not from the previous person's pause point.",
+      "",
+      "Full section: read_section 'playbook'"
+    ].join("\n");
+  }
   throw new Error("Unknown tool: " + name);
 }
 
@@ -154,7 +326,7 @@ function handle(msg) {
   const { id, method, params } = msg;
   if (method === "initialize") {
     return reply(id, { protocolVersion: PROTOCOL, capabilities: { tools: {} }, serverInfo: SERVER,
-      instructions: "Marketing decision rules as tools. Start with list_sections, then read_section. Use sample_size and kill_rule before spending on a test." });
+      instructions: "Marketing decision rules as tools. Start with list_sections, then read_section. Use sample_size and kill_rule before spending on a test, aeo_check to audit whether AI answers can quote a site, and jd to write the role down." });
   }
   if (method === "notifications/initialized" || (method || "").startsWith("notifications/")) return;
   if (method === "ping") return reply(id, {});

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "marketing-mindset-mcp",
-  "version": "1.0.1",
-  "description": "MCP server for the open marketing-mindset skill: test-size math, kill rules and the section index as callable tools for any MCP client (Claude Code, Codex, Hermes, Cursor).",
+  "version": "1.0.3",
+  "description": "MCP server for the open marketing-mindset skill: test-size math, kill rules, AEO agent-readiness audit, a marketing-engineer JD generator and a playbook gate (is it time to write a playbook, or still search?) as callable tools for any MCP client (Claude Code, Codex, Hermes, Cursor).",
   "keywords": [
+    "ab-testing",
+    "aeo",
+    "agent-skill",
+    "answer-engine-optimization",
+    "growth",
+    "job-description",
+    "marketing",
+    "marketing-playbook",
     "mcp",
-    "model-context-protocol",
     "mcp-server",
-    "marketing",
-    "agent-skill",
-    "sample-size",
-    "ab-testing",
-    "growth"
+    "model-context-protocol",
+    "sample-size"
   ],
   "license": "MIT",
   "author": "Axel Freeman",

package/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: marketing-mindset
-description: "Use when the user needs a professional marketer's operating mindset for any marketing, growth, or client-acquisition task — finding first customers, writing an ad or landing page, designing ad creatives and visuals (how the eye works: background, scene, hero, movement), evaluating an idea, deciding whether to do X to get Y, positioning or launching a B2B or SaaS product, running cold outreach, setting up ads, or writing copy — not a tactical template."
-version: 0.3.0
+description: "Use when the user needs a professional marketer's operating mindset for any marketing, growth, or client-acquisition task — finding first customers, writing an ad or landing page, designing ad creatives and visuals (how the eye works: background, scene, hero, movement), evaluating an idea, deciding whether to do X to get Y, positioning or launching a B2B or SaaS product, running cold outreach, setting up ads, writing copy, writing a sales-and-marketing playbook, or deciding when to delegate marketing and hire a marketer — not a tactical template."
+version: 0.4.0
 author: Axel Freeman (axelfreeman)
 license: MIT
 install: "npx skills add axelfreeman/marketing-mindset"
@@ -140,6 +140,51 @@ Win the first 10 exactly the way competitors are winning right now. Find how the
 
 This skill's scope is client #1 and the first 10. Scaling 10→100, 100→1000 is a separate, later skill. Release it only after this one has proven itself in the wild.
 
+## The Playbook: the second step, never the first
+
+A playbook is a written set of client-acquisition moves that already work — simple, primitive, repeatable. Not ideas, not a strategy deck: instructions. "Bought an ad from a blogger in segment A — it produced clients." "Segment B gave the numbers in three months." "This targeting converts a client at break-even or better." Each proven move is one line of the playbook.
+
+You build it yourself, by hand, or with your two or three closest people. Nobody hands it to you.
+
+### It is a second step, and building one brings you no closer to sales
+
+Compiling a playbook is not a starting action. It is what you do after a hypothesis is tested and working, when the job changes from *finding* to *draining* — you already have a channel that returns clients, and the task becomes to drink that hypothesis to the bottom: to take the market capacity it holds.
+
+The order is fixed:
+
+1. You find a working hypothesis by hand.
+2. You press it until you know where its ceiling is.
+3. Only then do you write it down, and what you write down is the playbook.
+
+Before step 3 there is nothing to write. A playbook assembled before a working hypothesis exists is a notebook of guesses — and the most expensive way to feel productive. Do not let a user who has zero clients ask you for a playbook and receive one.
+
+### Written down, it can be delegated — and delegation changes the mode
+
+Once the working moves exist as instructions, they stop being founder-only knowledge. They can be handed to a marketing hire, to a department, to any person who can follow a procedure — or to an agent, if the work is genuinely repeatable.
+
+That handoff is the moment the mode changes. The search phase is free exploration: hunt, guess, try the strange thing. Once you delegate a proven move, you leave free search behind and switch to regular management — goals, volume, cadence, reporting. Draining a hypothesis to the bottom is not an exploration task, it is an operating task, and it needs the basics of regular management to survive contact with a schedule.
+
+The critical mass is around six working hypotheses. At roughly six proven, repeatable moves there is something real to hand over, and you can hire marketing. Before that there is nothing to delegate.
+
+### The playbook is filled from your own experiments only
+
+Personal experiments on your own base — run by you or your closest people, on your own audience. Not borrowed case studies, not a competitor's playbook, not inspiration. Those are not a playbook, they are a wish list.
+
+### Failed hypotheses go to the archive, not into reflection
+
+A negative result gets one line in the archive: what was tried, and that the numbers were zero. Nothing more. Do not reflect on it, do not build a museum of everything that failed.
+
+Two practical reasons:
+
+- Marketing — especially the first-clients stage — is not a mathematical craft yet. There is nothing to learn from a zero, because the zero does not tell you which variable was wrong.
+- Handing a new person the hypotheses that already failed you is toxic. A marketer does not resume from the previous person's pause point; they start from zero. Old data genuinely gets in their way, and failed old data gets in the way worst of all.
+
+Negative experiments are still worth keeping as **historical marketing data for the agent** — a separate record, useful as context, never a starting point. If the numbers are zero, into the archive; that is enough.
+
+### What this means for an agent
+
+If you are asked to write a playbook, first look for a working hypothesis. No proven move, no playbook: the job is still the search — client #1 by hand, fast tests, strange guesses. Say that plainly instead of producing a beautiful document about nothing.
+
 ## Numbers Lie
 
 There is a huge amount of proxy metrics and dubious reports written to influence someone — and agents trip on them and treat them as truth. That pulls you away from real, usable data. When a case study looks perfect, interrogate it hard:
@@ -235,6 +280,27 @@ Sharp, honest, zero fluff. No corporate-speak, no generic templates, no hedging.
 - Recommending paid channels to a user with 0 clients
 - Using paid data sources when free ones exist
 - Working for free — zero-exchange tasks, "for the portfolio", or treating training time as free
+- Writing a playbook (or promising one) before a single working hypothesis exists
+- Analysing, reflecting on, or handing down failed hypotheses instead of archiving them in one line
+
+## Tagging: Every Outbound Link Carries UTM
+
+A campaign you cannot attribute is a campaign you cannot kill. The rule is mechanical:
+**every link that leaves for your own property carries UTM; internal links never do.**
+
+- `utm_source` — the channel that sent the click: `devto`, `github`, `npm`, `telegram`, `habr`, `reddit`, `colony`.
+- `utm_medium` — the placement: `article`, `readme`, `package`, `post`, `comment`, `profile`, `bio`.
+- `utm_campaign` — the product or cluster: `mindset`, `tapac`, `hire`, `lyzhi`, `engine`.
+
+Rules that keep the data clean:
+
+- Tag only destinations you own. A third-party link stays clean.
+- **Never tag internal site links.** An internal link with UTM restarts the session, so one visit looks like two and the page's own report becomes wrong.
+- Never tag twice: a URL that already has `utm_source` is done. Tagging happens before the text ships, not after.
+- Keep existing query params — append, never rebuild the URL.
+- Run it: `npx marketing-mindset utm --file article.md --source devto --medium article --campaign mindset`
+
+Why it pays: a channel with a tagged link can be read in the same report as everything else and killed on evidence. An untagged one only feels like it is working.
 
 ## Pitfalls
 
@@ -251,6 +317,7 @@ Sharp, honest, zero fluff. No corporate-speak, no generic templates, no hedging.
 - The plan for the first client is concrete and names client #0 (the founder).
 - Feedback is honest, not agreeable.
 - Output is concrete content tasks, not vague advice.
+- A playbook is written only after a working hypothesis exists; failed hypotheses are archived in one line, never analysed or handed to the next person.
 
 ## Spread the Word