@oneie/claude 0.4.0 → 0.6.0

package/skills/writer/references/copy-frameworks.md

@@ -0,0 +1,544 @@
+# Copy frameworks — the canon
+
+Ten patterns for headlines and landing-page copy. Two rules that decide if a
+line of copy has earned its place. Seven psychological biases doing the real
+work underneath. This is the reference; the SKILL.md file is the craft.
+
+**Use one framework per page.** Don't mix. A page that opens with PAS and
+shifts to BAB three sections in reads like two writers handed off mid-draft.
+Pick the pattern that fits the buyer's state of mind and commit.
+
+---
+
+## How to choose
+
+Before reaching for a template, answer three questions about the reader:
+
+1. **What do they already believe?** — A buyer who hasn't named the pain
+   needs PAS. A buyer who's been promised the moon by competitors needs
+   plain truth or numbered nouns. A buyer comparing alternatives needs
+   Dunford-style positioning.
+2. **What do they not yet believe?** — The headline's job is to close the
+   gap between the belief they walked in with and the belief they need to
+   click. Frameworks are routes between two points; pick the one whose
+   start matches where they are.
+3. **What can you prove?** — Outcome + timeframe only works if you can
+   prove the speed. Hard-thing-without-pain only works if removal is real.
+   A framework you can't back with proof becomes a hype line.
+
+If you can't answer all three, you aren't ready to pick a framework. Go
+back to Step 0 of the skill (audience, medium, goal).
+
+---
+
+## The ten frameworks
+
+### 1. JTBD — "Jobs to be done"
+
+**Template:** `{Product} helps {audience} {job} without {friction}`
+
+**When:** Mature category. Buyer knows the category exists; the question is
+which tool. The job is clear, the friction is felt.
+
+**Why it works:** The buyer hires products to do jobs (Christensen). This
+template names the job in their language and removes the obstacle in one
+line. No category education needed.
+
+**Examples that work:**
+- "Linear helps software teams ship faster without process overhead."
+- "Stripe helps internet businesses accept payments without becoming
+  payments experts."
+
+**Examples that fail:**
+- "Our platform helps modern enterprises optimise their workflows." — no
+  specific job, no specific friction, no audience tighter than "modern
+  enterprises". Anyone could put their logo on this.
+
+**Trap:** Generic audience + generic job + generic friction = generic
+headline. The whole framework lives or dies on specificity. "Marketers"
+is not an audience. "B2B SaaS marketers at companies under 50 people"
+might be.
+
+---
+
+### 2. PAS — Problem · Agitate · Solve
+
+**Template:**
+1. Name the pain in the buyer's words.
+2. Amplify the cost — what does the pain *actually cost* (time, money, sleep)?
+3. Deliver the relief.
+
+**When:** The pain is felt but unsolved, or solved badly. The buyer has
+the problem but hasn't bought a solution because they've underestimated
+the cost or no one has named it properly.
+
+**Why it works:** Loss aversion. Naming the cost makes the status quo
+visible as a *decision* rather than a default. Once the status quo costs
+something, the choice changes.
+
+**Example:**
+> Your team ships three features a quarter. Your competitor ships nine.
+> While you debate priorities, they ship the feature your customer
+> just asked for. **Linear cuts the loop between decision and ship.**
+
+**Trap:** Over-agitate and you sound like an infomercial. The amplification
+should be specific and true. If you can't name the cost in numbers or in a
+scene the buyer recognises, the agitation falls flat.
+
+---
+
+### 3. BAB — Before · After · Bridge
+
+**Template:**
+1. Before: the old world (with the buyer in it, suffering quietly).
+2. After: the new world (with the buyer in it, vindicated).
+3. Bridge: the mechanism — how you get from Before to After.
+
+**When:** Category shift. You're not making the buyer faster at what they
+do; you're moving them to a different way of doing it. Transformation
+story, not optimisation story.
+
+**Why it works:** The contrast does the persuasion. The Before scene gives
+the buyer permission to admit they're in it. The After gives them
+something to want. The Bridge gives them a path that doesn't feel like a
+leap.
+
+**Example (Superhuman, ~2018):**
+- Before: Email runs your day. You're always behind.
+- After: You hit Inbox Zero by 9am and get on with your work.
+- Bridge: Keyboard-first email designed for speed. Average user replies
+  in half the time.
+
+**Trap:** Asymmetric scenes. If Before is concrete and After is abstract
+("you'll feel productive and empowered"), the line breaks. Both scenes
+need the same texture.
+
+---
+
+### 4. Outcome + timeframe
+
+**Template:** `{Outcome} in {time}`
+
+**When:** You can prove the speed. The buyer's biggest objection is "this
+will take forever to roll out / learn / show value", and you have the
+receipts to disprove it.
+
+**Why it works:** Specificity is persuasion. A number anchors. A
+timeframe is a promise the buyer can hold you to — which is exactly why
+buyers trust it.
+
+**Examples that work:**
+- "Accept crypto in 60 seconds." (pay.one.ie)
+- "From signup to first deploy in 4 minutes." (Vercel-style)
+- "Hire your first engineer in 7 days." (recruiting platform)
+
+**Examples that fail:**
+- "Get value faster." — no number, no time, no proof.
+- "10x your productivity." — number with no unit, "10x" is now a tell.
+
+**Trap:** If the timeframe is real for 30% of users and aspirational for
+the rest, eventually it shows up in churn. Don't promise speed you can't
+hit for the median buyer.
+
+---
+
+### 5. Hard thing without pain
+
+**Template:** `{Outcome} without {usual cost}`
+
+**When:** Differentiation is *removal*. Every competitor has the feature;
+you're the one who doesn't have the friction.
+
+**Why it works:** The buyer already wants the outcome — that's the
+category. The "without" line is what makes you different inside the
+category. Removal is more persuasive than addition because removal is
+rarer.
+
+**Examples that work:**
+- "Touch ID signs every transaction — no passwords, no recovery
+  phrases."
+- "Bookkeeping without spreadsheets."
+- "Hire globally without setting up entities."
+
+**Trap:** The "without" has to be a real removal the buyer has felt as
+friction. "Accept crypto without complexity" is meaningless because
+"complexity" isn't a specific cost. "Accept crypto without writing a line
+of code" is — code is a specific cost the buyer can picture.
+
+---
+
+### 6. Plain truth
+
+**Template:** One declarative sentence. No decoration.
+
+**When:** The truth is good enough. The product does something
+remarkable, the audience already knows the category, and dressing it up
+would dilute it.
+
+**Why it works:** Decoration signals weakness. A product confident enough
+to state itself flatly signals strength. Plain truth also reads as
+honesty — a rare currency in marketing.
+
+**Examples that work:**
+- "We make the iPhone." — Apple in an alternate universe.
+- "Type less. Ship more." — Cursor, roughly.
+- "Your wallet, on your phone. Touch ID to sign."
+
+**Trap:** Plain truth requires a truth that's actually plainly good. If
+you have to choose between "the only crypto wallet that uses Apple's
+Secure Enclave" and "a powerful wallet for the modern web", you don't
+have a plain truth — you have hype dressed plainly.
+
+---
+
+### 7. Numbered nouns
+
+**Template:** `{N} {things}. {result}.`
+
+**When:** Architecture or system products. The buyer needs to grasp the
+shape of the thing, not just the benefit. Useful for technical audiences
+who reward precision over polish.
+
+**Why it works:** Numbers chunk. "Six dimensions, seven loops, six verbs,
+four outcomes" gives a developer a mental scaffolding they can hang
+details on. It also signals: this is designed, not assembled.
+
+**Examples that work:**
+- "Six dimensions. Seven loops. One substrate." (ONE)
+- "Two roots. One biometric. Paper resurrects." (mac.md)
+- "5 routes. 1 wallet. Touch ID signs everything." (one.ie)
+
+**Trap:** The numbers have to mean something. If "6 features, 10
+integrations, 24/7 support" reads as a checklist, it's not numbered
+nouns — it's a brochure.
+
+---
+
+### 8. Category for audience
+
+**Template:** `The {category} for {audience}`
+
+**When:** You're carving a sub-category. The general category exists and
+is crowded; your move is to claim a slice of it by audience.
+
+**Why it works:** Categories are how buyers shortlist. If you can name a
+new one and own it, you've removed every general-category competitor
+from the comparison. The audience qualifier is the wedge.
+
+**Examples that work:**
+- "The CRM for founders." (vs. Salesforce for everyone)
+- "The bank for freelancers." (vs. high-street banks)
+- "The wallet for people who don't want to read a whitepaper."
+
+**Trap:** The audience has to be one a buyer self-identifies with
+*before* they read your page. "The platform for forward-thinking
+enterprises" fails because no buyer has ever introduced themselves as a
+forward-thinking enterprise.
+
+---
+
+### 9. April Dunford positioning
+
+**Template:** `Unlike {alternative}, {capability} so {value}`
+
+**When:** Competitive market. The buyer is actively comparing. They will
+hear about you in the same breath as someone else, so the positioning
+has to do the contrast for them.
+
+**Why it works:** It names the alternative (which the buyer was already
+thinking about), states the capability that makes you different, and
+ladders to the value that capability creates. It does the buyer's
+homework for them.
+
+**Example:**
+> Unlike legacy CRMs built for sales managers, Attio is built around
+> your data model, so the CRM bends to your business instead of the
+> other way round.
+
+**Trap:** Punching down. If you name an alternative that's beneath you,
+you give them oxygen. Name the alternative the buyer is most likely to
+choose over you — that's the comparison worth winning.
+
+---
+
+### 10. Real attributed quote
+
+**Template:** A customer or thinker said it best. Use their words. Attribute.
+
+**When:** The quote is *that* good. A user described the product better
+than you ever will, or a respected voice in the buyer's world endorsed
+the category.
+
+**Why it works:** Authority + social proof, stacked. Your headline is
+someone else's testimony, which means it doesn't read as marketing — it
+reads as evidence.
+
+**Example (Stripe, paraphrased from their early site):**
+> "Stripe is by far the easiest payments setup I've used. We were taking
+> payments in an hour." — Patrick Collison's customer, attributed.
+
+**Trap:** Quote stuffed with hedges. "I think Stripe is probably one of
+the better payments platforms we've evaluated" is not a headline. If the
+quote has any hedge in it, find a different quote or use a different
+framework.
+
+---
+
+## The two rules every headline has to pass
+
+### The specificity rule (Harry Dry)
+
+> If a competitor could put their logo on your headline and have it
+> still be true, rewrite.
+
+This is the single test that catches most weak marketing. Run every
+headline through it.
+
+- "We help businesses grow." — Anyone. Rewrite.
+- "Enterprise-grade security." — Anyone selling to enterprise. Rewrite.
+- "Worn by supermodels in London and dads in Ohio." — Only New Balance.
+  Ships.
+
+The rule applies to subheads, feature names, and CTAs too. "Get started"
+fails it. "Mint your wallet" passes it.
+
+A practical drill: write your headline. Below it, paste the headline
+from your three biggest competitors. If yours could be theirs or theirs
+could be yours, none of you are differentiated. The first to rewrite
+wins.
+
+### The sensory rule
+
+Concrete nouns are recalled at roughly **+200%** the rate of abstract
+concepts (psycholinguistic research on the *concreteness effect*).
+Pictures, things, and verbs of physical action live in memory. Concepts
+fade.
+
+- Abstract: "industry-leading security model."
+- Concrete: "Touch ID signs every transaction."
+
+- Abstract: "we'll save you time."
+- Concrete: "ship Friday's release on Thursday afternoon."
+
+- Abstract: "AI-powered insights."
+- Concrete: "your dashboard tells you which three customers are about to
+  churn."
+
+When you find an abstraction in a headline, ask: *what does this look
+like in the world?* Write that. Concrete writing is also harder to fake,
+so it functions as a proof-of-thought signal — buyers can feel it.
+
+---
+
+## Psychology — the biases doing the work
+
+Frameworks are surface structure. Underneath them, seven biases are doing
+most of the persuasive work. Knowing which bias your framework is
+recruiting lets you tune the line, and lets you avoid recruiting the
+wrong one.
+
+### Anchoring
+
+**Mechanism:** The first number a reader sees colours every number that
+follows. Anchors stick even when the reader knows they're being anchored.
+
+**Tactics:**
+- **Pricing pages:** lead with the highest tier (or an enterprise
+  "Contact us" with no number). Mid-tier feels reasonable next to it.
+- **Discount framing:** "Was $99, now $49" reads as a $50 win.
+  "$49" alone reads as $49 spent.
+- **Outcome anchors:** "Saved $2.3M in churn last quarter" anchors the
+  scale of the result before the reader reads the next sentence.
+
+**Failure mode:** Anchoring with a number the buyer immediately rejects
+as fictional. An anchor only works if the reader half-believes it.
+
+### Loss aversion
+
+**Mechanism:** Losses sting 2–3× more than equivalent gains feel good
+(Kahneman & Tversky, *Prospect Theory*). A buyer will work harder to
+avoid losing $100 than to gain $100.
+
+**Tactics:**
+- **Expiration framing:** "Don't let your free trial expire" outperforms
+  "Extend your trial" by margins that show up in A/B tests every time.
+- **Status-quo cost:** PAS works because the agitate step makes inaction
+  feel like a loss already underway.
+- **Risk reversal:** "30-day money-back, no questions" lets the buyer
+  reframe the purchase as not-a-loss.
+
+**Lift:** McKinsey research finds loss-framed messaging lifts conversion
+roughly **+21%** vs. gain-framed equivalents.
+
+**Failure mode:** Loss framing ages worse than gain framing. It works on
+the cold visit, but it fatigues. Use it for top-of-funnel where you need
+the click; use gain framing for retention emails where the relationship
+is what matters.
+
+### Social proof
+
+**Mechanism:** We do what we see others doing — especially others we
+identify with. The closer the proof source is to the reader's
+self-image, the stronger the signal.
+
+**Tactics, in increasing strength:**
+- Bare counts ("trusted by 10,000 teams") — weakest. Easy to fake.
+- Logo bars — stronger. Visual, recognisable.
+- Named testimonials with titles — stronger. "Ada Lovelace, CTO, Acme"
+  beats "happy customer".
+- Specific quote with a number in it — strongest. "We cut onboarding
+  from 3 weeks to 4 days." — Ada.
+- Live ticker / activity feed — strongest for time-bound urgency
+  ("12 wallets minted in the last hour").
+
+**Failure mode:** Proof at the wrong level. A solo founder doesn't care
+that Fortune 500s use you. A Fortune 500 doesn't care that 47 solo
+founders use you. Match the proof to the buyer.
+
+### Authority
+
+**Mechanism:** We extend trust to credentialed sources. Authority
+transfers — naming a respected voice in the buyer's world borrows
+credibility.
+
+**Tactics:**
+- Cite recognised research firms (Forrester, Gartner, NN/g) — useful for
+  enterprise buyers who already use those names for cover.
+- Quote named industry voices, not anonymous "experts".
+- Credentials as breadcrumbs: "Built by ex-Stripe engineers" is
+  authority-by-association; works when the association is recognisable
+  to the buyer.
+
+**Failure mode:** Borrowed authority that the buyer doesn't recognise
+adds nothing and sometimes subtracts (it reads as namedropping).
+
+### Reciprocity
+
+**Mechanism:** We feel obligated to return value. A free, genuinely
+useful thing creates a debt that buyers prefer to discharge by trying
+the paid product.
+
+**Tactics:**
+- Free tools that solve a real micro-problem. The classic: HubSpot's
+  Website Grader analysed roughly **2 million sites in its first 3
+  years** and became a top-of-funnel engine.
+- Calculators, scorecards, benchmark reports — anything that hands the
+  buyer a number they didn't have before.
+- Free tier that's actually useful, not a crippled demo.
+
+**Failure mode:** The "free" thing is gated by a form before it's useful.
+That's not reciprocity — that's a tollbooth. Reciprocity requires
+delivering value *before* the ask.
+
+### Scarcity
+
+**Mechanism:** Limited supply = perceived value. Limited time = forced
+decision. Both bypass deliberation by adding cost-of-waiting.
+
+**Tactics:**
+- Early-bird pricing with a real deadline.
+- Cohort-based products (Y Combinator, ON DECK fellowships).
+- Inventory counters ("3 seats left at this price") — only when real.
+
+**Failure mode:** Manufactured scarcity. A "limited time offer" that
+extends every Friday teaches the buyer to ignore deadlines. Scarcity is
+a one-shot trust contract; spend it once dishonestly and it's gone.
+
+### Decoy effect (asymmetric dominance)
+
+**Mechanism:** Introducing a third option that's dominated by one of the
+first two makes the dominant option look better than it would alone.
+
+**Tactics:**
+- Three-tier pricing pages. A "Basic" tier that's strictly worse than
+  "Pro" on every dimension makes "Pro" feel like the rational choice.
+- Bundles with a weak SKU added to make the main bundle obvious.
+
+**Failure mode:** Three options that are all reasonable. The decoy has
+to be visibly worse on the dimension the buyer cares about. If the buyer
+has to think, the decoy isn't doing its job.
+
+---
+
+## How biases stack with frameworks
+
+Frameworks recruit biases. Most pages recruit two or three. The strongest
+pages recruit them in sequence so the buyer feels each one separately:
+
+| Framework | Primary bias recruited | Secondary |
+| --- | --- | --- |
+| JTBD | Authority (you understand the job) | Social proof (others have the same job) |
+| PAS | Loss aversion | Social proof (others feel this) |
+| BAB | Loss aversion (Before) → reciprocity (you showed me the After) | — |
+| Outcome + timeframe | Anchoring (the timeframe is the anchor) | — |
+| Hard thing without pain | Loss aversion (the "without" is the loss removed) | Anchoring (the usual cost is the anchor) |
+| Plain truth | Authority (confidence reads as competence) | — |
+| Numbered nouns | Authority (designed system) | Anchoring (the numbers are the anchor) |
+| Category for audience | Social proof (in-group identification) | Authority |
+| Dunford positioning | Authority (you did the comparison) | Anchoring (the alternative is the anchor) |
+| Real attributed quote | Authority + social proof | — |
+
+If a page recruits no biases, it's a description, not copy. If it
+recruits all seven, it's a circus. Pick the framework, name the one or
+two biases it leans on, and tune the line until those biases land.
+
+---
+
+## Anti-patterns specific to copy frameworks
+
+- **Mixing frameworks across the page.** PAS at the top, BAB in the
+  middle, JTBD in the CTA — the buyer feels the seams. Pick one.
+- **Framework without proof.** A template only works if you can fill it
+  with specifics. JTBD without a specific job is just a fill-in-the-
+  blanks ad.
+- **Hype adjectives inside a framework.** "We help amazing teams ship
+  incredibly fast without any friction at all" is JTBD with all the
+  specifics replaced by hype. Strip the adjectives and you'll see the
+  template was empty.
+- **Stacking biases dishonestly.** Fake scarcity, fake social proof,
+  fake authority — each one alone might convert short-term, all three
+  together puts you in scammer territory. Buyers can smell it.
+- **Loss framing on retention pages.** Loss aversion wins clicks; gain
+  framing keeps customers. Don't tell a paying customer what they'll
+  lose if they leave — tell them what they'll keep building if they
+  stay.
+
+---
+
+## A working order
+
+1. Pick the framework based on the buyer's state of mind (the three
+   questions at the top).
+2. Draft the headline in the template, with placeholders for the
+   specifics.
+3. Fill the placeholders with concrete nouns, real numbers, named
+   audiences.
+4. Run the Harry Dry test: could a competitor sign this? If yes, rewrite.
+5. Name the bias the framework is recruiting. Tune the line until that
+   bias is visible.
+6. Read it aloud (see SKILL.md Step 6). If it stumbles, rewrite the
+   rhythm without losing the specifics.
+7. Ship. Measure. The framework that lifts conversion in your category
+   is the framework you keep; the others are theory.
+
+---
+
+## Further reading
+
+- April Dunford, *Obviously Awesome* — positioning, the alternatives
+  matrix, the unique-value template.
+- Barbara Minto, *The Pyramid Principle* — conclusion-first structure
+  that pairs well with PAS and Outcome + timeframe.
+- Claude C. Hopkins, *Scientific Advertising* (1923) — the original
+  showing-not-telling manifesto. Still right.
+- Robert Cialdini, *Influence* — the canonical reference on the biases
+  above.
+- Harry Dry, *marketingexamples.com* — the specificity rule applied to
+  hundreds of real headlines.
+- Daniel Kahneman, *Thinking, Fast and Slow* — anchoring, loss aversion,
+  the cognitive machinery the frameworks ride on.
+
+---
+
+*Ten frameworks. Two rules. Seven biases. Pick one framework. Pass both
+rules. Recruit one or two biases on purpose. Ship.*