@aicopycoders/exodus 2026.9.1100-beta.2 → 2026.9.1400-beta.0

package/assets/skills/mechanism/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: mechanism
+description: Luke's way of finding a product's mechanism (the unique mechanism of the problem and of the solution) for each segment and persona: one problem, one solution, simple, intuitive, visual, concrete, never multi-headed. Use it whenever someone asks "what's the mechanism", "what's our UMP / UMS", "why does this work", "name the problem", "what's the ingredient story", "find the lock", "which ingredient leads", "what mechanism for this persona", or wants mechanism ideas from the Genesis bots (Universal Mechanism Bot, Health Mechanism Matrix Bot, and the supporting characterizations, metaphors, and surprising-culprit bots). It reads the competitor mechanism file first, uses the bots for breadth, then filters everything through the simplicity criteria and matches the survivors to the product's unique features (star ingredient, booster, delivery, founder, story) until the story locks. Runs inside the positioning-spiral as the features station and hands the chosen mechanisms to copy-instincts and the writing pipeline. Needs GENESIS_API_KEY plus a provider key in .env for the bot calls; works without them as a conversation.
+---
+
+# Mechanism
+
+A mechanism is the story of why the problem happens and why this product fixes it. The best ones are two links long. A student's mechanism has six moving parts and nothing rhymes; a great one is "your hormones deplete, so your cells can't absorb" and the star ingredient is the thing that opens the door. This skill exists to keep mechanisms that simple, to find them per segment rather than once for the brand, and to match each one to the feature that makes it ownable.
+
+Think mode until a bot run or a competitor scrape. Those are build bursts: say the plan and cost back in two lines, get the go, run, then come back with a short list. Read `thinking-vs-build` if installed.
+
+## The rules
+
+1. **One problem, one solution.** Two links maximum: A happens → B is the symptom. The fix inverts A. If it needs a third link it is not a mechanism yet, it is a paragraph.
+2. **Simple, intuitive, visual, concrete.** A ten-year-old gets it in three seconds. It can be drawn on a whiteboard. It matches how the problem feels in the body (stuck → flowing, heavy → light, wired → settled). "It's like a [familiar thing] for [this]" completes without effort.
+3. **Not multi-headed.** One cause. Not "hormones and cortisol and gut". If the market believes three causes, pick the one this segment believes and leave the others for other segments.
+4. **The name implies the fix.** A pulse can be quieted, a leak plugged, a switch flipped, gunk cleaned. Cannibal brain cannot be un-eaten. Name it in two or three words: body thing plus what it is doing wrong.
+5. **Per segment, per persona.** A mechanism that explains the 3AM wake does not explain rage at the kids. Build the map cell by cell; some cells share a mechanism, most do not.
+6. **Ownable.** The mechanism must land on a unique feature so no competitor can say it the same way. Star ingredient alone. Star × booster. Star × delivery. Star × booster × delivery. Feature × founder. Feature × story. Supporting ingredients never lead.
+7. **Zeitgeist counts, borrowed words are fine, saturated words are not.** If the market already says "cortisol", use it and take the unowned corner of it (night cortisol, not belly). If four strong brands own the exact phrase, move one word over.
+8. **Psychology first, then make it true.** Decide the mechanism that would be most intuitive, then check the science can carry it and the compliance team can live with it. Facts-first produces the same mechanism everyone has.
+
+## Inputs
+
+- The product's features: formula with doses, form factor and timing, founder and story, process, proof. From the `positioning-spiral` features station or the brief.
+- The segment grid and any personas: the outcome, sub-outcome, and the Belief facet for each cell. From `odf`.
+- The competitor mechanism file (below). From `find-competitors` and the rip.
+- Voice-of-customer quote banks: the words they use for the cause ("I think it's my hormones", "wired but exhausted").
+
+## Step 1. The competitor mechanism file
+
+Before generating anything, know what the market is already being sold. One file, one row per competitor mechanism, built from the ad bank, the swipe file, and the sheet from `find-competitors`. Template and the operations to run on it are in `references/competitor-mechanisms.md`. The short version:
+
+- **UMP census:** count competitors by the mechanism word they sell. Crowded words are proven; empty words are either unowned or unwanted.
+- **Corner map:** for each crowded word, which corner do they own (cortisol → belly, face, morning) and which corners are empty (cortisol → night).
+- **The visual each one uses**, the name each one gives the problem, and the two-link version of their story. If their story cannot be written in two links, that is a weakness you can beat.
+- **What they blame** (the industry, a food, a habit, the body) and **what they absolve**.
+
+Output in think mode: the three or four crowded words, the empty corners, one line each.
+
+## Step 2. Breadth from the bots
+
+The bots produce more candidates than a person will, and they are meant to be over-generated then cut. They also tend to be over-complicated; that is what Step 3 is for.
+
+Which bot:
+- **Supplements and anything with a body mechanism:** `health-mechanism-matrix-bot`. It builds a 12-mechanism research prompt from the 12-box matrix (structure / function / element × too much / too little / out of balance / dysfunctional), then ranks the top four on five criteria (understand, attention, visualise, A→B path, body-feel) out of 50. Told to "run the full process" it ranks from its own knowledge without waiting for external research.
+- **Everything else, and a second pass on supplements:** `universal-mechanism-bot`. 36 candidates from the 9-box matrix, scored on zeitgeist 40, intuitive simplicity 40, novelty 20, top three with hooks.
+- **After a mechanism is chosen:** `characterizations-bot` for 20 names and a top three, `metaphors-bot` for the visual, `surprising-culprit-bot` for the villain angle, `segmentmech-swapper-bot` to swap the mechanism into an existing winner.
+
+How to call them: the `genesis-bots` skill's helper, one call at a time (one concurrent stream per key), output to a file in the folder. Prompt templates that produce the shape this skill needs are in `references/bot-prompts.md`. The prompt always carries the constraint: one problem, one solution, two links, star ingredient named, competitor words listed so the bot avoids the crowded corners.
+
+Cost: each bot run is one long completion on the provider key (a few cents to a few tens of cents). Say it back before running.
+
+Run one bot per segment cell you are working, not one per brand. Save each output inside the active brand's folder, under `<brand>/state/mechanisms/<segment-slug>/<bot>.md` (run `npx @aicopycoders/exodus brand current` first; never write one brand's material into another brand's folder).
+
+## Step 3. Cut to simple
+
+Take every candidate (bot output, competitor corners, your own) and put it through this in order. Most die at the first gate.
+
+1. **Two links?** Write it as "A → B". If it needs "and" or a third arrow, cut or collapse it.
+2. **One cause?** If it names two causes, split it into two candidates or cut one.
+3. **Draw it.** One picture. If you cannot draw it, simplify until you can.
+4. **Barista test.** Say it while ordering coffee. If it needs a setup sentence, cut.
+5. **Body-feel.** Does the solution match how the problem feels? Wired → settled, not wired → "optimised".
+6. **Belief match.** Does it use the cause this segment already believes, or one they will accept in a sentence? A mechanism the persona has to be taught is a mechanism for a different persona.
+7. **Name implies fix.** Rename until it does.
+8. **Corner check.** Against the competitor file: is this word crowded, and if so is this the empty corner?
+9. **Plausibility.** Can the science carry the two links at the doses in the bottle? Mark the rung compliance will pull.
+
+Survivors get the bot's scores if it gave them, otherwise score simplicity, zeitgeist, and novelty 40/40/20 by hand. Keep the top three per cell.
+
+## Step 4. Find the lock
+
+For each surviving mechanism, match it to the unique feature that makes it ownable. Try the combinations in this order and stop at the first that rhymes:
+
+| Shape | Question |
+|---|---|
+| Star alone | Does the star ingredient's natural story explain the fix by itself? |
+| Star × booster | Does one partner make the two-link story stronger without adding a link? |
+| Star × delivery | Does the form factor or timing carry the mechanism (evening gummy active at 3AM; sublingual in 20 minutes; patch while you sleep)? |
+| Star × booster × delivery | Only if all three say the same thing in different languages. Three dials, one rhyme. |
+| Feature × founder | Does the founder's background make them the natural discoverer? |
+| Feature × story | Does the origin, process, or place carry it (untouched land, forged rock)? |
+
+Then the lock test from `copy-instincts`: one breath, no "and also", pain and solution share a root metaphor, the spokesperson is irreplaceable, proof is a chapter of the story. Write the one-breath version. If it does not lock, go back to the competitor file or the bots with the constraint tightened.
+
+Sympathetic magic belongs here: what does the star ingredient's source do in nature that maps to the fix? Use it if it rhymes, drop it if it needs explaining.
+
+## Step 5. The mechanism map
+
+One row per segment cell that has a chosen mechanism. Lives in the active brand's folder as `<brand>/state/mechanism-map.md` and feeds the ingredient-story column of the segment grid.
+
+```
+# <Brand> — <Product> — Mechanism Map (v<n>, <date>)
+
+| Segment (O → sub · D · F) | Problem, named | A → B | Solution, named | Lock (star / booster / delivery / feature) | One picture | Belief it uses | Competitor corner | Proof rung | Compliance rung |
+
+## One-breath versions
+- <segment>: "<one breath>"
+
+## Cut and why
+- <candidate> — died at gate <n>: <reason>
+
+## Bot runs
+- <segment>: health-mechanism-matrix-bot → <brand>/state/mechanisms/<slug>/health.md (top pick: …)
+```
+
+Hand-offs: `copy-instincts` for the story and the hooks (the mechanism is the curiosity block), `characterizations-bot` and `metaphors-bot` for names and visuals, the writing pipeline for ads, and back to `positioning-spiral` for the catalog collision check (a mechanism a sister SKU already claims is a collision).
+
+## Worked example: Evenkeel Reset Gummies (fictional)
+
+Evening gummy: saffron 30mg, magnesium glycinate 200mg, rhodiola 100mg. Founder a former ER night-shift nurse. Segment: women 45 to 60 who fall asleep fine and wake at 3AM, many on HRT and still waking, melatonin fails, Belief facet "hormones or cortisol".
+
+**Step 1.** Competitor file: cortisol is crowded (four strong brands) but they own belly, face, and morning. Sleep-onset is crowded and fatiguing. Peri hormone-balance is crowded. Empty corner: night cortisol, "stay asleep".
+
+**Step 2.** `health-mechanism-matrix-bot` with the template prompt. Top four, scored out of 50: 3AM Cortisol Pulse (45), Serotonin Night Drain (44), HPA Brake Failure (40), Sleep-Guard Signal Collapse (39). Its own read: lead with the pulse because it borrows the word competitors already taught and takes the unowned night corner; the evening gummy timing becomes the delivery story.
+
+**Step 3.** Pulse: two links (cortisol fires too early and too hard → brain snaps awake). One cause. Drawable (a flare at 3AM on a line that should slide downhill). Barista: "your cortisol fires at 3AM instead of 6". Body-feel: snapping awake, exactly what they describe. Belief: cortisol, already held. Name implies fix: a pulse can be quieted. Corner: empty. Plausible at the doses with saffron's HPA evidence; "the only thing shown to quiet it" is the rung compliance pulls. HPA Brake Failure died at gate 1 (three links). Sleep-Guard died at gate 4.
+
+**Step 4.** Star × delivery locks: saffron quiets the pulse, and an evening gummy is in the blood at 3AM when the pulse fires. Magnesium as booster adds no link, so it stays supporting. Founder rhymes: an ER nurse lived the 3AM surge every shift. One breath: "You don't have a falling-asleep problem, you have a 3AM cortisol pulse. It fires too early and snaps you awake. An evening saffron gummy is active in your blood at 3AM to quiet it, so you sleep through."
+
+**Step 5.** Row written. Serotonin Night Drain held for the melatonin-fails persona as its own row. Collision check: Glow Collagen keeps belly and face; night is clear.
+
+## What this skill is not
+
+It does not position the brand (positioning-spiral), map segments (odf), or write ads. It finds the two-link story per segment, proves it is ownable, and hands it on.
+
+## Standards
+
+Before producing anything, read `STANDARDS.md` at the workspace root (and the section for this output type). Grade the draft against it before showing it; rewrite failures first. When the user reacts with a judgment, a banking phrase, or the same note twice, hand the reaction to `remember-that`. At the end of the session, `handoff` scrapes the chat and proposes entries.

package/assets/skills/mechanism/references/bot-prompts.md

@@ -0,0 +1,94 @@
+# Bot prompts for the mechanism skill
+
+All calls go through the `genesis-bots` helper, one at a time:
+
+```
+node .claude/skills/genesis-bots/scripts/genesis-stream.mjs <bot-slug> <prompt.txt> <out.md>
+```
+
+Slugs (confirm against the live list; they can change): `health-mechanism-matrix-bot`, `universal-mechanism-bot`, `characterizations-bot`, `metaphors-bot`, `surprising-culprit-bot`, `segmentmech-swapper-bot`.
+
+Limits: one concurrent stream per key, 60 requests a minute. Each run is a long completion on the provider key. Run per segment cell, save under `state/mechanisms/<segment-slug>/`.
+
+## The constraint block (goes in every prompt)
+
+```
+CONSTRAINT: I want ONE problem and ONE solution. Two links maximum (A happens → B is the symptom; the fix inverts A).
+Simple, intuitive, visual, concrete. No multi-headed mechanisms. Name the problem in two or three words and make the name imply the fix.
+Star ingredient: <name>. It must lead. <Booster> may support. <Delivery / timing> may carry the mechanism. Supporting ingredients never lead.
+Avoid the crowded corners: <list the competitor words and the corners they own>. Take an empty corner if one exists.
+Keep the output compact.
+```
+
+## health-mechanism-matrix-bot (supplements)
+
+Tested prompt shape. Output: STEP 1 a research prompt covering 12 matrix mechanisms; STEP 2 a scoring table (Understand, Attention, Visualise, A→B Path, Body-Feel, total /50), the top four with mechanism, ingredient fix, criterion notes, marketing application and weakness, then a final recommendation. Told to "run your full process", it ranks from its own knowledge instead of waiting for external research. If you want the deeper version, take its STEP 1 research prompt, run it yourself (with the model, or a research tool the user has approved), paste the findings back to the bot, and ask it to re-rank.
+
+```
+PRODUCT: <name>. <form factor and timing>. <formula with doses>. <founder and story in one line>.
+
+SEGMENT / PERSONA: <outcome → sub-outcome · demographic · facets>. <what they have tried>. <what they believe causes it>. Money symptom: <the one they would pay anything to erase>.
+
+COMPETITOR MECHANISMS ALREADY IN MARKET: <from the competitor file: word → who owns it → which corner>. Nobody strong owns <empty corner>.
+
+<constraint block>
+
+Run your full process on this.
+```
+
+## universal-mechanism-bot (any market; second pass on supplements)
+
+Output: 9-box matrix × 3 examples each with names, a scoring table (zeitgeist 40, intuitive simplicity 40, novelty 20), top three with why-it-works and implementation notes. It will produce 27 to 36 candidates; expect most to be too complex, that is what Step 3 of the skill is for.
+
+```
+BUILD A BUYER: <persona card or the ODF coordinate with self-ID line, tried-and-failed, belief>.
+
+MARKET INFORMATION: <sophistication in one line>. <competitor mechanism census: the crowded words and their corners>. <zeitgeist words the market is using this quarter>.
+
+OFFER BRIEF: <product, features, star ingredient or feature, delivery, founder, proof, transformation>.
+
+<constraint block>
+
+Generate the full matrix, score it, and give the top 3. For each of the top 3 also write the A → B in one line and the one picture I would draw on a whiteboard.
+```
+
+## characterizations-bot (after a mechanism is chosen)
+
+```
+MECHANISM (UMP): <A → B in one line>. Problem name so far: "<name>".
+SOLUTION (UMS): <the fix in one line>. Star: <ingredient or feature>. Delivery: <form/timing>.
+SEGMENT: <coordinate and self-ID line>.
+AVOID: names that imply the problem is permanent (eating, mutated, degenerating). Names must imply the fix.
+Give 20 characterizations, classified UMP / UMS, then a ranked top 3 with one line on why each would stop the scroll.
+```
+
+## metaphors-bot (the one picture)
+
+```
+UMP: <A → B>. UMS: <the fix>. Body-feel of the problem: <how it feels, in their words>. Body-feel of the fix: <the opposite>.
+Give natural, mechanical, and object metaphors. Prefer ones I can draw in one frame and feel in the body (termites, not bulldozers). Mark the three you would put in a hook.
+```
+
+## surprising-culprit-bot (the villain, when the thesis needs one)
+
+```
+PROBLEM: <money symptom>. SEGMENT: <coordinate>. MECHANISM: <A → B>.
+What they are doing now to fix it: <the tried-and-failed list>.
+Give 15 surprising culprits where something they trust or do every day is the cause. Rank by which the segment would believe in one sentence. Blame the product or the industry, never the person's body or discipline.
+```
+
+## segmentmech-swapper-bot (aim a winner at a new cell)
+
+```
+WINNING AD: <full transcript or copy>.
+KEEP: the structure, beat order, proof, offer, CTA, certainty.
+SWAP: the mechanism from "<old A → B>" to "<new A → B>" and the segment from <old coordinate> to <new coordinate>, self-ID line "<line>".
+Change only the lines the swap forces. List every line you changed.
+```
+
+## Reading bot output
+
+- Take the scoring tables as a first sort, not a decision. The skill's Step 3 gates decide.
+- Bots over-complicate. A "mechanism" with three arrows is two mechanisms or a paragraph. Collapse or split.
+- Bots invent numbers and studies. Anything with a percentage or a citation gets marked as the compliance rung until checked.
+- Keep the bot's "potential weakness" lines; they are usually right.

package/assets/skills/mechanism/references/competitor-mechanisms.md

@@ -0,0 +1,39 @@
+# The competitor mechanism file
+
+One file per brand, inside that brand's folder: `<brand>/inputs/competitor-mechanisms.md`. One row per mechanism a competitor sells, built from the ad bank, the swipe file, and the FOLLOW rows of the competitor sheet. It is the thing you read before generating anything, because the market has already paid to learn which words work.
+
+## Row template
+
+| Competitor | UMP word (the belief they sell) | Corner (which symptom or moment they own) | Problem, named (their words) | A → B (their story in two links, or "3+ links") | Solution, named | Star ingredient or feature | Visual they use | What they blame | What they absolve | Longest run (days) | Source (ad id) |
+
+Rules for filling it:
+
+- Their words, not yours. If the ad says "cortisol face", write that, not "elevated cortisol".
+- One row per mechanism, not per ad. Ten ads on the same story is one row with the longest run.
+- If their story cannot be written in two links, write "3+ links" and quote the extra link. That is a weakness.
+- The visual is what is on screen when the mechanism is said: the diagram, the diagnosis overlay, the metaphor object.
+- What they blame and what they absolve are the thesis: "the industry sold you falling asleep", "your body is fine".
+
+## Operations to run on the file
+
+**UMP census.** Count rows by UMP word. Crowded words are proven demand. Empty words are unowned or unwanted; the reviews decide which.
+
+**Corner map.** For each crowded word, list the corners owned and the corners empty. Cortisol: belly, face, morning owned; night empty. Gut: bloating, biofilm owned; mood empty.
+
+**Two-link test.** How many competitor stories are two links? The ones that are not can be beaten on simplicity alone.
+
+**Visual census.** Which pictures repeat (the diagram, the doctor skit, the before-and-after body)? A repeated picture is a proven picture and also a saturated one.
+
+**Blame map.** Who is the villain across the set? An enemy nobody has named is an open lane.
+
+**Ingredient map.** Which star ingredients carry which mechanisms? If three brands lead with ashwagandha on cortisol, ashwagandha cannot be your star on cortisol.
+
+**Plain-word check.** For each UMP word, count it in reviews and comments (the voice-of-customer files). A word that is in every ad and few human mouths is competitor coinage; the plain word underneath it is the one to map.
+
+## Output in think mode
+
+Three lines, then the next axis:
+
+- Crowded: <word (n brands)> · <word (n)> · <word (n)>
+- Empty corners: <word → corner> · <word → corner>
+- Beatable on simplicity: <competitor, 3+ links>

package/assets/skills/odf/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: odf
+description: Luke's ODF method (Outcome × Demographic × Facet) for finding who to sell to, one axis at a time, in a recursive think-mode loop. Use it whenever someone wants segments, sub-outcomes, personas, a segment grid or map, "who else is out there", "map the market", "find the pockets", "build personas from the comments", "horizontal scaling", "ODF", or wants to aim an existing winning ad at a new segment. Three entry points: MAP (no winners yet, build the grid and focus order), PERSONAS (turn chosen segments into named humans that live in Exodus), HORIZONTAL (a winner exists, swipe it into each new persona, Mad Libs not rewrites). Trigger even when the user only names one axis ("let's list the outcomes", "what are the facets here", "add menopause as a segment") because the axes change each other. Runs with nothing installed: a conversation, whatever data they have, this file. Pushes into Exodus with `npx @aicopycoders/exodus segment`.
+---
+
+# ODF
+
+There are two ways an ad account grows with creative. Vertical is same people, more to say to them. Horizontal is new people. A segment is not a vibe. It is one outcome, one demographic, and a facet or two: "3AM · women 45 to 60 · on HRT and still". Change any part and it is a different human and usually a different ad. Most accounts slice on outcome and demographic. The gold is in the facets and the sub-outcomes.
+
+The sentence to keep: ads are made of parts, some proven and some cheap to swap, so every launch should be one cheap swap away from something proven. A new segment is the expensive swap. This method makes sure the segment is real before anyone pays for it.
+
+## Think mode, always
+
+This runs as a back-and-forth. One axis per message. Every item one or two words. Propose a list, let the user cut it, move to the next axis. No document until the axis is agreed, and no grid until every axis is agreed. The user makes every call, fast, by name or by number. When they say "stress test", apply the rules and show only what moved. When they say "are we missing anything", check the data for the biggest themes not on the list and name at most three. When they say "note your place", say what is done, what is missing, what is next, then wait.
+
+Research inside an axis (rip these ads, scrape these reviews) is a build burst: say the plan back in two lines, get the go, run it comprehensively, write files early, then come back to the list. Read the `thinking-vs-build` skill if installed.
+
+## The grammar
+
+**Outcome** is the spine. What the buyer wants fixed, one or two words. Each outcome breaks into sub-outcomes through five lenses: type (which kind), location (where it shows), function (what stops working), moment (when it hits), severity (how bad). Function and severity cuts make different humans (dead bedroom versus weak erections). Moment cuts usually make symptom lines, not humans.
+
+**Demographic** is what you could tick from across the room: gender, age band, race or ethnicity, buying for whom, occupation, life stage, medical identity. Include the groups the product is not for yet. Mark exclusions.
+
+**Identity** is who they say they are: the one who holds everyone together, not a pill person, the researcher, gym guy. It is its own axis in the map because the user audits it separately and it is where casting and voice come from. It also lives in Exodus as a demographic row and as a facet family, so on export the same list goes to both.
+
+**Facet** is why they are here, invisible from across the room. Four families in the map: **Belief** (what they think causes it), **State** (a condition, what they are on, what they tried), **Value** (what they prefer), **Occasion** (something that happened; it has a date). Two laws of a good facet: it is self-verifiable in one second ("do you sit six hours a day?"), and it usually carries its mechanism (sitting → blood flow), which half-explains the problem before the ad does. A facet also sets awareness: "just hit menopause" is problem-aware; "tried three cleanses that failed" is solution-aware and needs a failure-explainer, not an intro. Record awareness on the facet; never make it an axis or you count the same human five times.
+
+**Three words that are not the same thing.** A *Belief facet* is the mechanism the market already believes (cortisol, hormones, gut). The *UMP* is the mechanism a competitor sells as its positioning; competitors are grouped by UMP. The *ingredient story* is this product's mechanism per sub-outcome (star ingredient plus at most one partner plus the form factor); it lives in the folder grid and in the copy, not in Exodus. Keep the three apart in every list.
+
+**Persona** is one segment named as a human, with a self-ID line built from their words, a quote bank, and a first transplant.
+
+## Stress-test rules (apply on every axis)
+
+- One or two words per item. If it needs a sentence it is not an item yet.
+- Different human, not a synonym. Merge sub-outcomes that describe the same person.
+- Nothing in two rows. 3AM lives in Sleep, not in Menopause or Cortisol.
+- States and occasions are facets, not outcomes. "On HRT", "doctor shrugged" go under State and Occasion.
+- Mechanisms are not outcomes unless the market adopted the word as the problem (cortisol qualifies; its row holds the visible symptoms).
+- Life stages can be outcomes when buyers name the stage as the problem ("my peri symptoms"), and also stay as a layer over the other rows.
+- **The AI-artifact test.** A phrase in many ads and few human mouths ("2PM crash", "wired but tired", "brain fog") is a copy line, not a segment. Count it in reviews and comments, not in ads. Does it split the market into a different human who needs a different ad? If not, it is copy.
+- Competitor coinage ("stress bloat") is not the market's word. Map the plain word.
+- Formula fit. Drop outcomes the product cannot honestly touch.
+- Refuse new markets in disguise. A sub-outcome that needs new proof is a different account. Keep the outcome, add a facet.
+- Compliance-hot words (anxiety, panic, disease names) can be sub-outcomes, not headline outcomes. Mark them.
+- Exclusions are not segments. A contraindication goes in the medical list marked as an exclusion.
+- Check the other gender and the other ages after every facet list. The user will.
+
+**Evidence when arguing an item:** own winning ad > long-running competitor ad > comment under a running ad > review or Reddit quote > logic. Quote the proof exactly, never summarise it. Mark pure logic HYPOTHESIS. Never hide your own inventions.
+
+## Entry point 1: MAP
+
+Use when there is no agreed grid yet, whether or not winners exist.
+
+1. **Load what they have** and say it back in one paragraph: product and fixed formula, the outcome it sells today, who buys now, what is winning and fatiguing, the sister SKUs it must not collide with, and the market's words (own ads, competitors' longest-running ads, comments, reviews, Reddit). Never edit a quote.
+2. **Outcomes.** Ask for their starting list. Sort each item into outcome, Belief facet, demographic, or copy line. Propose additions from the data. Get to six to ten.
+3. **Sub-outcomes.** Three to five under each, through the five lenses. Stress-test. Then "are we missing anything" against the biggest themes in the data (energy and fatigue is the usual one).
+4. **Focus order.** Two or three lanes with a simple argument from ads, competitors, reviews, and logic. The user decides.
+5. **Demographics.** Gender, age bands, race, buying for, occupation, life stage, medical with exclusions.
+6. **Identity.** From comments, reviews, the brand's own cast, and the ads with the best hold. Include the other gender's versions.
+7. **Facets by family.** Belief, State, Value, Occasion. Sources: reviews ("what I tried", "what I replaced"), Reddit, comments, competitor ads (what they name and disqualify), logic (the conditions the category obviously has: shift worker, on a GLP-1, on an SSRI, postpartum). Each facet gets its one-second self-ID line and the mechanism it carries. Check both genders.
+8. **Ingredient story** per sub-outcome, if the user wants mechanisms in the grid: star ingredient in every one, at most one partner, plus the form factor. Supporting cast never leads.
+9. **Full list**, then the SKU collision check, then write the grid (template below), then the three homes: folder, Exodus, shareable.
+10. **Segments seen.** Keep a running list in the folder of every segment spotted in a competitor ad or the brand's own ads that is not in the grid yet ("that's always a segment too"). Add to it in every session.
+
+When ads exist, tag every ad, theirs and competitors', to one cell by its net impression. Shaded cells are taken, empty cells are gaps. Rank gaps by size, urgency of the outcome, who is already there, and zeitgeist.
+
+## Entry point 2: PERSONAS
+
+Use when the grid is agreed and the user wants humans to write for. Personas live in Exodus; the folder keeps the quote banks.
+
+1. **The tiered list**, as one numbered chat message. Every segment worth a persona in three tiers: Tier 1, you should have these (proven on two sides, or the obvious missing column); Tier 2, recommended (real signal on one side); Tier 3, could do (hypotheses, cheap to test small). Name the human, not the outcome: *HRT-and-Still Helen (Sleep → 3AM · women 45 to 60 · on HRT and still)*. Each line: name, coordinate, proof in a phrase, what changes in the ad. The user answers by number.
+2. **The persona card** for each one picked. Short, because it has to fit the dashboard:
+   - Name (the human)
+   - Coordinate: outcome → sub-outcome · demographic values · identity · one or two facets
+   - Awareness the facet sets
+   - One-second self-ID line, in their words
+   - What they tried that failed, and what they will not hear
+   - Ingredient story for this cell
+   - First transplant: which existing winner to aim at them, and the only things that change
+   - Quote bank: five to ten exact quotes with source, kept in the active brand's folder at `<brand>/state/personas/<slug>.md`, referenced from the card
+3. **Push to Exodus.** Export first, then add personas to the contract, then import.
+
+## Entry point 3: HORIZONTAL
+
+Use when a winner exists and the job is new people. Do not go horizontal too early: if two segments are printing, squeeze them first.
+
+Aim every existing winner at every new persona. Mad Libs, not rewrites. The winner's skeleton transfers word for word: sentence count, line breaks, rhythm, beat order, mechanism, proof, offer, CTA, certainty. Only the segment payload moves: the self-ID line, the symptoms and scenes, what they tried, the words from the quote bank. Most sentences of a good pass are untouched. Never add a beat, an explainer, a risk line, or an urgency line the winner does not have. Never soften a line. Then ten extra hooks per swipe in the persona's own words. A swipe that wins validates the segment. A swipe that loses says the segment is real but needs its own ad, or is not real.
+
+Hand the swipes to the writing pipeline; this skill does not write finished ads.
+
+## Exodus
+
+The dashboard map is Plan → Map. The CLI is the edit surface and the JSON contract is the document:
+
+```
+npx @aicopycoders/exodus brand current                       # right brand first
+npx @aicopycoders/exodus segment export --out segments.json   # pull the current map (empty is fine)
+# edit segments.json
+npx @aicopycoders/exodus segment import segments.json          # dry-runs, prints changes
+npx @aicopycoders/exodus segment import segments.json --yes    # only if it would delete or archive
+npx @aicopycoders/exodus segment show                          # verify
+npx @aicopycoders/exodus segment personas --json               # saved personas
+```
+
+Rules of the contract, learned the hard way:
+
+- Import is a full replace matched by name. Names missing from the file get deleted; personas they orphan get archived. The CLI refuses without `--yes` if anything would be deleted.
+- The dashboard keeps exactly five demographic rows: Buyer, Gender, Age, Race / Ethnicity, Identity. Extra rows are dropped silently. Fold life stage into Age values, occupation into Identity, medical into the State facet family.
+- Facet families in Exodus are Belief, Identity, State, Value, Occasion. Send the Identity axis to both the Identity demo row and the Identity facet family.
+- There is no ingredient-story slot. Mechanisms stay in the folder grid.
+- The persona object shape is not documented in `segment --help` and exports empty on a fresh map. Before the first persona push, export, look for an existing persona object, and if there is none, write one persona with `name`, the coordinate slugs (`outcome`, `sub`, `demos`, `facets`), and a `notes` field holding the self-ID line and first transplant, then let the dry-run tell you what the server accepts. Log the shape in tool feedback once known.
+
+## Grid template (folder copy)
+
+```
+# <Brand> — <Product> — Segment Grid (v<n>, <date>)
+
+## OUTCOMES (spine)
+| # | Outcome | Sub-outcomes |
+
+## DEMOGRAPHICS (tick from across the room)
+| Gender | Age | Race | Buying for | Occupation | Life stage | Medical (exclusions marked) |
+
+## IDENTITY (who they say they are)
+<a> · <b> · <c>
+
+## FACETS (why they're here)
+| Belief | State | Value | Occasion |
+
+## INGREDIENT STORY (star in every one; at most one partner; form factor)
+| Outcome | Sub-outcome | Lead ingredients |
+
+## FOCUS ORDER
+1. <outcome → sub · demographic · facet> — one-line argument
+
+## SEGMENTS SEEN (not in the grid yet)
+<a> · <b>
+
+## COVERAGE GRID (persona names; blank = gap)
+| Outcome | <demo col> | <demo col> | … |
+```
+
+## Worked example: Evenkeel Reset Gummies (fictional)
+
+Saffron, magnesium glycinate, rhodiola, evening gummy. Founder a former ER nurse. Sister SKUs Night Tea and Glow Collagen. Twelve tested ads, best hold on a 3AM-waking ad, "stress" ads fatiguing.
+
+**MAP, pass 1, outcomes.** User's list: stress, sleep, cortisol, menopause, mood, energy. Sorted: stress is a Belief facet and a copy line, not an outcome (three human mouths in 400 posts; "3AM" in 115). Cortisol stays (the market adopted the word). Menopause stays as an outcome and a layer. Agreed: Sleep, Mood, Cortisol, Menopause, Energy, plus Cravings from the review data.
+
+**Sub-outcomes, Sleep.** 3AM · Racing mind · Light sleep · Hangover. "Can't fall asleep" dropped: that is Night Tea's lane. Stress test moved "night sweats" out of Sleep into Menopause.
+
+**Focus order.** 1. Sleep → 3AM · women 45 to 60 · on HRT and still (own best ad, competitor Dawnfield running the 3AM angle 140 days, 115 quotes). 2. Mood → Rage · the peri woman. 3. Cravings → Night hunger, as a stack with Glow Collagen. Hold: Energy (rhodiola is a morning herb), Cortisol belly (collagen owns it).
+
+**Facets, State.** On HRT and still · Melatonin fails · Magnesium stopped · Wine to sleep · Off an SSRI (exclusion, serotonergic herb). Self-ID line for the first: "Are you on HRT and still up at 3?" Mechanism carried: HRT fixes hormones, not the night surge. Awareness: solution-aware, needs a failure-explainer. Other-gender check added: men 45+ who wake at 4AM, HYPOTHESIS.
+
+**PERSONAS, tiered list.** Tier 1: HRT-and-Still Helen (Sleep → 3AM · women 45 to 60 · on HRT and still). Tier 1: Melatonin-Fails Marie (Sleep → 3AM · women 45 to 60 · melatonin puts her down not keeps her down). Tier 2: Rage-in-the-Car Renée (Mood → Rage · women 45 to 60 · snapped at the kids). Tier 3: 4AM Frank (Sleep → 3AM · men 45+ · HYPOTHESIS). User picks 1 and 2.
+
+**Card, Helen.** Self-ID: "on HRT and still wake at 3am every night." Tried and failed: HRT, magnesium, a sleep tea. Will not hear: "manage your stress". Ingredient story: saffron + magnesium glycinate, evening gummy. First transplant: the 3AM ad, with the opening line swapped to the HRT self-ID and the "tried" beat swapped to HRT and magnesium; every other sentence untouched. Quote bank in `state/personas/hrt-and-still-helen.md`.
+
+**HORIZONTAL.** The 3AM winner is aimed at Helen and Marie. Two swipes, same skeleton, two payloads, ten hooks each in their words. Marie's swipe wins; Helen's does not. Helen is real (115 quotes) but needs her own ad with the failure-explainer up front. That goes to the writing pipeline as a brief.
+
+## What this skill is not
+
+It does not choose formats, styles, or conceits. It does not write finished ads. It does not decide the mechanism story on its own; that is the `positioning-spiral` loop calling this skill as its targets station and the `copy-instincts` skill for the story itself.
+
+## Standards
+
+Before producing anything, read `STANDARDS.md` at the workspace root (and the section for this output type). Grade the draft against it before showing it; rewrite failures first. When the user reacts with a judgment, a banking phrase, or the same note twice, hand the reaction to `remember-that`. At the end of the session, `handoff` scrapes the chat and proposes entries.

package/assets/skills/patterns-and-gaps/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: patterns-and-gaps
+description: Luke's pattern-finding and gap-finding method. Patterns are anything that occurs more often than chance and has salience, weighted by judgment, taste, and psychology, found in four places: the brand's own account, competitor accounts, organic content, and research (reviews, comments, Reddit). Gaps are what competitors and organic are doing, read through the anatomy of ads, that the brand is not doing yet, and what nobody is doing that the data says someone should. Use it whenever someone asks "what patterns do you see", "what do these have in common", "what's working across these", "what are they doing that we aren't", "where are the gaps", "what's nobody doing", "what should we steal", "compare our account to theirs", hands over a swipe file, an ad bank, a comment dump, a review corpus, or a Scout export and wants the read. Also the standing question after any rip or scrape. Patterns are found layer by layer using the anatomy-of-ads grid (WHO × WHAT × HOW × CREATIVE), so an ad set becomes comparable data before anything is counted.
+---
+
+# Patterns and gaps
+
+The whole job, underneath everything, is looking for patterns. A pattern is anything that shows up more often than it should by chance and means something. Counting finds the "more often". Judgment, taste, and psychology decide the "means something". A gap is the space between what the market has proven and what the brand is doing, or between what the data says people want and what anyone is selling.
+
+Think mode for the read, build mode for the counting. Read `thinking-vs-build` if installed.
+
+## Where patterns live
+
+Four sources, each read differently and weighted differently.
+
+| Source | What it tells you | Weight | How you read it |
+|---|---|---|---|
+| Own account | What this audience actually paid for. Hook, hold, revenue, spend. | Highest. A pattern here is proof. | Sort by result, read the top and the bottom raw, then count. |
+| Competitor accounts | What the market has paid to learn. Run-days, reuse, active count. | High, if the brand is strong (the `find-competitors` sheet says). | Longest-running first. A pattern across three or more strong brands is proven. One brand is a hypothesis. |
+| Organic content | What people share without being paid. Outliers versus a creator's average. | Medium for angles and hooks, high for zeitgeist and language. | Outliers only (a post at 10x the account's normal). The Scout library in Exodus holds these when the brand is set up. |
+| Research | Reviews, comments, Reddit, in their own words. | High for language, pain, and segments. Low for formats. | Counted mentions per term, quote banks with reference numbers, the 7-lens read. |
+
+Evidence ladder when a pattern is argued: own winning ad > long-running competitor ad > comment under a running ad > review or Reddit quote > logic. Mark logic HYPOTHESIS.
+
+## The layers (from `anatomy-of-ads`)
+
+Patterns are found layer by layer, not on the whole ad. Tag every ad with the anatomy grid first, then count per layer:
+
+- **WHO**: segment (Outcome × Demographic × Facet), persona, awareness caught at
+- **WHAT**: concept (the flat fact) · angle (the family and the role starred) · mechanism (UMP, UMS, brand gate, the name) · copy blocks present and missing · copy beats present, overbuilt, unreached
+- **HOW**: hook (which beat promoted, intensity, type) · structure (medium, skeleton, conceit, style)
+- **CREATIVE**: static (native, template type, branded) · video (conceit, actor, style, terrain, setup)
+
+The swap-cost rule orders what a pattern is worth: segment and mechanism patterns are driver-level (get them wrong and you are at zero); style and conceit patterns are cosmetic (cheap to copy, cheap to swap). A pattern in a cheap layer with the expensive layers held constant is the cheapest test in the account. Read `anatomy-of-ads` for the tag sheet and the tests per layer; the `message-isolator` Genesis bot dissects a single ad into its layers with exact quotes when one deserves the full read.
+
+## Step 1. Load and normalise
+
+Get everything into one table with the same columns, whatever the source. The ad bank is that table for own and competitor ads. For organic, the Scout export. For research, the quote banks and counts. If the sources are in different shapes, normalise before reading; a pattern across sources only shows when the columns match.
+
+Read the raw material before counting. Top ten and bottom ten by result, read in full. The pattern you feel on the read is the hypothesis the counting tests.
+
+## Step 2. Find patterns
+
+Run these operations per source, then across sources. Write the count next to every claim.
+
+**Frequency.** What repeats, per layer? Which segments, angle families, mechanism words, beats, hooks, skeletons, conceits, styles, template types. Count it. "Symptom stack → single diagnosis" appeared in nine of twenty-three cortisol competitor ads across four brands. That is a pattern. Two of twenty-three is a note.
+
+**Salience.** Of the things that repeat, which land? Weight frequency by result: hook rate and hold on own ads, run-days and reuse on competitor ads, outlier multiple on organic, helpful votes on reviews. A thing that repeats and wins outranks a thing that only repeats.
+
+**Co-occurrence.** What shows up together? Fake-authority actor with a diagnosis conceit. Timeline close with a week-by-week proof. Symptom stack with a named mechanism. These pairs are the reusable parts.
+
+**Structure.** Same idea, same beat order across brands? The order is the pattern, not the words. Write it as a sequence: slap hook → symptom list → "it's cortisol" → dismiss the alternatives → mechanism → put you on the product → timeline → offer.
+
+**Language.** Which phrases are in many ads and few human mouths (competitor coinage, copy lines) and which are in many human mouths and few ads (unclaimed language)? The second list is gold. Count both against the research corpus.
+
+**Segments seen.** Every demographic, state, or occasion a competitor calls out goes on the running list for `odf`.
+
+**Absence.** What does the top set never do? No one uses the founder. No one names the night. No one shows a man. Absence in a strong set is either a gap or a graveyard; the research decides which.
+
+**Negatives are data.** The one-star reviews, the comments that argue, the ads that died. A pattern in what fails is as useful as one in what works.
+
+Then apply judgment, taste, and psychology to rank: does the pattern explain why it works (psychology), does it feel right against everything you have seen (taste), and would it survive a hostile read (judgment)? Say which of the three you are leaning on. A pattern with a count and a psychological reason beats one with a count alone.
+
+## Step 3. Find gaps
+
+Gaps come in three kinds. Look for all three, in this order.
+
+**Kind 1: they do it, we don't.** Lay the competitor pattern set against the brand's own account, layer by layer on the anatomy grid. Every proven pattern (three or more strong brands, or one brand at 90 plus days) the brand has not run is a gap. These are the cheapest wins because the market has already paid to prove them. Output: a list of proven patterns not yet in the account, with the layer they live in and the competitor ad to model.
+
+**Kind 2: nobody does it, the data says someone should.** Lay the research against the competitor set. Words with high counts in human mouths and low counts in ads. Segments in the reviews that no strong brand addresses. A visible symptom nobody has named. An enemy nobody has blamed. A corner of a crowded mechanism word left empty (the `mechanism` skill's corner map). Output: the empty cells with the count that says they are real, marked with the evidence rung.
+
+**Kind 3: we do it, it's fatiguing, and there is a proven replacement.** The brand's own patterns that have stopped working (hook rate falling, the word "stress" in every fatiguing ad) set against what competitors run instead. Output: what to retire and what to swap in.
+
+Rank gaps by: size of the evidence, urgency of the outcome (usually the pain), how many strong brands prove it, how cheap it is to test (one cheap swap away from something proven beats a new segment), and zeitgeist. Then taste. Name the top three and stop; the rest go in the file.
+
+## Step 4. Hand back
+
+In think mode, a short list:
+
+```
+Patterns (counted, salient):
+1. <pattern> — <layer> — <count / n> — <why it works, one line>
+2. …
+Language they say that nobody sells: <word (n)> · <word (n)>
+Segments seen: <a> · <b>
+Gaps:
+1. <kind 1 / 2 / 3> — <the gap> — <evidence rung and count> — <the cheap test>
+2. …
+Hold (thin): <a> · <b>
+```
+
+In build mode, the full pattern file `<brand>/inputs/patterns-<source>-<date>.md` (inside the active brand's folder) with the operations above as sections, every count, every quote with its reference, and the gap ranking at the end. Write the "patterns across the set" section at the top of every swipe file, the way the competitor swipe already does.
+
+Hand-offs: proven patterns go to the production plan as clusters and formats; language gaps go to `mechanism` and `copy-instincts`; segment gaps go to `odf`; retire-and-swap goes to the testing plan.
+
+## Standing checks
+
+- Every pattern has a count. Every gap has an evidence rung. "Feels like" is allowed only when labelled taste.
+- The AI-artifact test on every language pattern: in ads or in mouths?
+- A pattern from one brand is a hypothesis. From one strong brand's 90-day ad it is a strong hypothesis. From three brands it is proven.
+- Absence is not automatically a gap. Check the graveyard (inactive ads with long past runs) before calling an empty space open.
+- Re-run the read after every rip, scrape, or new batch of own results. Patterns move.
+
+## Worked example (fictional)
+
+Evenkeel Reset Gummies. Own account: twelve tested ads, best hold on a 3AM-wake story, "stress" ads fatiguing. Competitor swipe: twenty ads across six strong brands. Research: 9,000 reviews across sleep and cortisol categories, quote banks counted.
+
+Patterns: symptom stack → single diagnosis (11 of 20, four brands, longest 289 days). Fake-authority diagnosis conceit (8 of 20, three brands). Named mechanism the viewer has not heard (all six brands). Week-by-week timeline close (7 of 20). Dismiss the alternatives by name (9 of 20; melatonin and magnesium named most). Language in mouths not ads: "wake up at 3am" (115 in reviews, 2 in ads), "wired but exhausted" (0 in reviews, 14 in ads: copy line, not a segment).
+
+Gaps. Kind 1: the brand has never run a symptom-stack lead or a fake-authority diagnosis; both proven across three or more brands; model the 289-day ad. Kind 2: nobody sells "stay asleep" or names the night; 115 mentions say the buyer is there; corner of cortisol is empty; the founder is an ER night nurse and no competitor uses a founder at all. Kind 3: retire the word "stress" (in all four fatiguing ads, 3 mentions in 9,000 reviews); swap in the 3AM language.
+
+Top three: symptom-stack lead aimed at the 3AM cell (kind 1, cheapest), the nurse-founder diagnosis conceit on the night corner (kind 1 and 2 together), retire "stress" for "3AM" across the account (kind 3).
+
+## What this skill is not
+
+It does not find the competitors (find-competitors), name the mechanism (mechanism), or write the ads. It reads what is there, counts it, weighs it, and says where the space is.
+
+## Standards
+
+Before producing anything, read `STANDARDS.md` at the workspace root (and the section for this output type). Grade the draft against it before showing it; rewrite failures first. When the user reacts with a judgment, a banking phrase, or the same note twice, hand the reaction to `remember-that`. At the end of the session, `handoff` scrapes the chat and proposes entries.