Copywriting

Contract

Field	Bound contract
Trigger	Write or fix product or marketing copy, landing pages, UI strings, or brand voice, or remove AI tells (page); design or review a bottom-of-article CTA (cta); write a hook, lede, or accroche for long-form content (hook).
Authority	Reversible local. Writes only user-facing copy and brand voice outputs in the working tree; cta and hook modes emit chat output only. Rollback is version control. No remote mutation.
Side effect	Creates or edits copy files and brand voice outputs in page mode; cta and hook modes produce conversation only.
Done	Page: copy is free of AI-isms, matches the voice chart, and fits the page type. Cta: the full recommendation structure is composed. Hook: the user has selected a hook and its commitments are named.

Inputs

• Mode selector: page, cta, or hook. Auto-detect from the ask: a bottom-of-article call-to-action routes to cta; a hook, lede, or accroche for long-form content routes to hook; anything else routes to page. An explicit mode argument overrides auto-detection.
• Mode page: copy to fix, or a page type and goal. Select the editing branch when copy exists or the user pasted it; the writing branch when nothing is written yet. For a genuinely ambiguous request ("improve this" with no copy in scope), ask one question, then commit.
• Mode cta: article context, primary objective, audience and relationship, funnel stage, and mechanism preference, collected in the interview step.
• Mode hook: topic, audience, target language (EN, FR, or both), approximate length, and publication venue; an optional existing draft opening, treated as Option 0 and never silently discarded.
• Optional inputs, settled before writing: page purpose, audience, product, traffic source, and any voice file (VOICE.md, BRAND.md, docs/voice.md). If an input is missing, infer it and name the inference so the user can correct it against real copy.

Procedure

Auto-detect the mode. Do not ask which mode; infer it from the ask.

Mode page: writing new copy

1. Gather context. Settle four fields before writing, from the user or from files; infer and name any field the files do not settle. (1) Page purpose: the one action this page drives. (2) Audience: the specific reader, their job title, pain, and what they have already tried. (3) Product: what it does and the concrete user outcome. (4) Traffic source: where the reader comes from. Traffic source sets temperature: cold needs more Why; warm can lead with How or What. Done when: all four context fields are settled from the user or files, with inferences named.

2. State the brief, then write. State the brief and keep going; mark every inferred field so the user corrects it against copy, not against a question. Stop and ask before writing only when a wrong guess makes the work useless or unsafe: the copy ships in this turn with no review, or the goal is genuinely unknown and each candidate goal produces different copy. Done when: the brief is stated with inferred fields marked, or the run stops because a wrong guess would make the work useless.

3. Discover brand voice. Check these sources in order and stop at the first match. (1) A voice file in the repo (VOICE.md, BRAND.md, docs/voice.md); authoritative when it exists. (2) Existing copy: README headers, copy files, or shipped marketing pages. (3) Inference: B2B SaaS direct and confident, consumer apps warmer, developer tools terse and honest. A discovered voice outranks the word lists: if the voice file or shipped copy uses a listed word as a signature, keep it. Locale and spelling convention come from the voice. When no voice file exists and the product will need one, offer to write VOICE.md alongside the copy using the voice chart structure below. Voice is constant (the brand personality); tone adapts to the reader's state: Done when: brand voice is discovered from the first matching source, with locale and spelling convention recorded.

   Reader state	Tone	Example
   Frustrated (error, failure, block)	Empathetic, solution-first, never blaming	"Payment failed. Your card was declined. Try a different card."
   Confused (first use, complex feature)	Patient, one step at a time	"Connect your bank to see spending insights. We'll walk you through it."
   Confident (routine task, return visit)	Efficient, minimal	"Saved"
   Cautious (high stakes, data loss)	Serious, transparent, no nudging	"Delete account? You'll lose all data and this can't be undone."
   Successful (completion)	Positive, proportional, brief	"Your changes are live."

   A tone shift is not voice drift; drift is when the copy reads as a different brand, not the same brand in a different moment.

4. Choose framework and load page norms. Route on what the copy is. Product-state copy (error, empty, success, loading, permission) or an action label: apply the UI state copy rules below and stop; persuasion frameworks do not apply to a button that deletes something. Marketing copy: pick the primary framework from the brief and layer freely: Done when: the framework is chosen and page norms are loaded, or UI state copy rules are applied for product-state copy.

   Situation	Lead framework
   Cold traffic, unfamiliar product	Why/How/What (Simon Sinek)
   Feature-heavy product	Benefit Not Feature
   High-trust audience, low awareness	Show Don't Tell
   Transactional page, known intent	CTA Clarity
   Long-form sales page	Problem → Agitate → Solution (PAS)

   The nine frameworks: Why/How/What (lead with Why, not What; order Why → How → What), PAS (name the pain, amplify the cost, present the solution), AIDA (Attention → Interest → Desire → Action for cold traffic), StoryBrand (customer is hero, product is guide; never make the product the hero), BAB (Before → After → Bridge; warmer and aspirational vs PAS confrontational), Show Don't Tell (replace adjectives with a specific fact, number, or scenario), Benefit Not Feature (lead with the outcome for the user; mention the mechanism only after the benefit is clear), Sentence Economy (every sentence earns its space; cut openers like "In order to", "It is important to note that"), CTA Clarity (action verb + what they get + qualifier; never two CTAs with the same verb on one screen). For a known page type, apply its norms:

   • Homepage: establish what the product is and who it is for; pick the highest-value segment and write for them. Sections in order: hero (lead with Why), social proof above fold, problem/pain, solution/benefits (one benefit per point), how it works, testimonials, final CTA. Do not add a secondary CTA that dilutes the primary action.
   • Landing page: drive one action; message must match what brought the reader. Headline mirrors the ad or email promise. PAS for problem-aware traffic, AIDA for cold. One CTA only; strip navigation and footer links.
   • Pricing page: help visitors choose. Name plans by buyer type, not tier ("Solo / Team / Company" beats "Basic / Pro / Enterprise"). Sections: value restatement, plan comparison (2-4 plans), feature differentiators, FAQ, social proof by tier, risk reversal near the CTA.
   • Feature page: connect a feature to an outcome for visitors already evaluating. Feature → Benefit → Outcome chain. Skip broad setup; go straight to the specific outcome with a number or example.
   • About page: build trust; every element passes the "so what does this mean for me?" test. Mission as a customer benefit, origin story tied to the customer's frustration, human team, 3-5 customer-relevant values, a CTA pointing to the product.

5. Write 2-3 alternatives. Label them Option A, B, C. Three for a page, hero, or campaign; two for a single string like a CTA or subject line. Each applies the chosen framework visibly, leads with Why, uses no banned word, includes a headline, subhead, and at least one CTA, and is structurally different, not the same idea with new adjectives. Done when: 2-3 labeled alternatives are written, each structurally different with no banned words.

6. Recommend and explain. Pick one; state which and why in one sentence. For each unpicked option, give one specific edit note. Done when: one option is recommended with a one-sentence reason and one edit note per unpicked option.

7. Verify every line before handing back. Check each line of every option: leads with Why, names a concrete outcome, no banned word, no em dash or stand-in. Check the option whole: it does not hand the brief's wording back (prompt echo), and every specific the user supplied appears rather than a stock default. New copy containing a banned word is not an option to present; rewrite it first. Done when: every line of every option passes the verification checks (Why-led, concrete outcome, no banned word, no em dash, no prompt echo, specifics present).

Mode page: editing existing copy

Set the edit posture first. Point edit: the user named one line, word, or section; change only the target plus minimum connective tissue; do not turn a point edit into a page audit. Restoration: the copy has a clear voice, angle, or opinion; preserve its vocabulary level, emphasis, omissions, sentence shape, and positioning; fix specific failures without rebalancing the argument. Rebuild: the copy is generic, contradictory, or has no perspective; reconstruct from the brief, but never invent proof.

1. Read all copy-bearing files. Scan every reader-facing surface: README headers, landing components, hero, CTAs, product descriptions, feature lists, onboarding strings, meta descriptions, email subjects. Read the voice file too if one exists; it settles register and locale and overrides the word lists for any word it names as a signature. Ask which files if unclear; never audit copy not read in context. Done when: every copy-bearing file is read, including the voice file if one exists.
2. Set the value proposition. Write one sentence before auditing: "[User] can now [do X] without [old pain]." Every flag and rewrite serves it. If the sentence cannot be written confidently, ask; the copy is unfixable until the value proposition is clear. Done when: the value proposition is stated in one sentence or the run stops because it cannot be written confidently.
3. Audit against persuasion frameworks. Check every major copy block against the nine frameworks and carry forward only the highest-impact problems; the flag budget is set in Step 6. Done when: every major copy block is checked against the nine frameworks with only highest-impact problems carried forward.
4. Remove AI writing patterns. If the user asked for AI pattern removal, run this first, before the sweeps. Flag each AI-ism with [AI-ISM] plus its type. Tier 1 words (always replace): delve, landscape (metaphor), tapestry, realm, paradigm, embark, beacon, testament to, robust, comprehensive, cutting-edge, leverage (verb), pivotal, underscores, meticulous, seamless, game-changer, utilise, nestled, vibrant, deep dive, unpack, showcase, unlock, intricate, holistic, actionable, impactful, learnings, thought leadership, best practices, synergy, in order to, due to the fact that, serve as, commence, keen (as intensifier). Tier 2 clusters (flag when 2+ in one paragraph): harness, navigate, foster, elevate, unleash, streamline, empower, bolster, spearhead, resonate, revolutionise, facilitate, underpin, nuanced, crucial, ecosystem (metaphor), myriad, plethora, catalyse, transformative, cornerstone, paramount, burgeoning, nascent, overarching. Tier 3 (flag only at high density, ~3%+): significant, innovative, effective, dynamic, compelling, unprecedented, exceptional, remarkable, sophisticated, world-class, state-of-the-art. Structural patterns: formulaic openings ("In the rapidly evolving world of..."), rhetorical-question openers, engagement hooks ("Here's the thing", "Plot twist:"), copula avoidance ("serves as", "features", "boasts"), synonym cycling, vague attributions ("Experts believe"), significance inflation, false ranges, em dashes and --/spaced-hyphen stand-ins (zero, in headings and body alike; a single occurrence is a failure). Chatbot artefacts (remove entirely): "I hope this helps", "Great question", "Let's dive in", any "let's + verb" transition, chain-of-thought leaking ("Let me think step by step", "Step 1:"), acknowledgement loops. Drafting tells (survive a word-level pass; check separately): prompt echo (the draft reuses the brief's own phrasing), generic default over the supplied specific (a real number or name replaced by a category placeholder), uniform confidence (every line lands at the same pitch). Severity triage: P0 (credibility killers: cutoff disclaimers, chatbot artefacts, vague attributions, significance inflation, a supplied specific replaced by a generic default) fix immediately; P1 (prompt echo, Tier 1 words, template phrases, "let's" openers, formulaic openings, engagement hooks, bold overuse, any em dash) fix before publishing; P2 (generic conclusions, compulsive rule of three, uniform paragraph length, announced honesty, copula avoidance, overused transitions, Tier 2 clusters) fix when time allows. A clean P0+P1 pass is publishable. Done when: AI writing patterns are flagged with [AI-ISM] labels and triaged by severity, or skipped when not requested.
5. Run seven sweeps. Run all seven in order; each targets a distinct failure mode. Flag everything before fixing. (1) Clarity: confusing structure, unclear pronouns, undefined jargon, claims readable two ways. Flags [JARGON], [VAGUE]. (2) Voice and tone: formal/casual shifts, register mismatch; identify the dominant voice and standardise to it. Flag [VOICE-DRIFT] on the line that reads as a different brand, not where the same brand meets a different moment. (3) So what: every claim answers "why should the reader care?". Flags [DEAD-WEIGHT], [FEATURE-NOT-BENEFIT]. (4) Prove it: back every claim with a named testimonial, case study, stat, or third-party validation. Flag [NO-PROOF]; use [PLACEHOLDER: add proof: stat / testimonial / example] when the proof is unknown. (5) Specificity: replace vague time, quantity, and outcome with concrete detail. Flag [VAGUE]. (6) Emotion: name the pain the reader already feels before selling the outcome; mirror the reader's actual state at this point in the page. Flag [PAIN-NOT-NAMED]. (7) Zero risk: remove friction at and near CTAs; address objections, add trust signals, clarify the next step, add risk reversal. Flag [WEAK-CTA] on any CTA standing alone without a qualifier or trust signal. Finish with the compound adjective hyphenation pass: hyphenate a multi-word modifier before the noun it describes ("a 7-day free trial", "real-time updates", "{{days}}-day free trial"); leave it open when it stands alone as a noun phrase ("The trial lasts 7 days"); never hyphenate an -ly adverb ("a fully managed service"). Fix hyphenation silently rather than flagging it. Done when: all seven sweeps are run in order with flags applied before fixes, and the hyphenation pass is complete.
6. Flag weakest elements. Attach an inline label to every weak line, using exactly these labels: [WHAT-NOT-WHY] (leads with product, not motivation), [FEATURE-NOT-BENEFIT], [TELL-NOT-SHOW] (adjective claim without proof), [VAGUE], [PASSIVE], [VOICE-DRIFT], [PAIN-NOT-NAMED], [DEAD-WEIGHT], [JARGON], [NO-PROOF], [WEAK-CTA], [STATE-COPY] (vague, leaky, or dead-end state string, or a destructive CTA labeled Confirm/OK/bare verb; apply the UI state copy rules below before using this label), [AI-ISM]. Flag the 3-7 weakest elements, prioritised by impact; over-flagging dilutes into a list nobody acts on. One occurrence is one flag; do not stack [TELL-NOT-SHOW] and [AI-ISM] on the same word. Done when: the 3-7 weakest elements are flagged with inline labels, prioritised by impact.
7. Rewrite flagged sections. Cut hard (same meaning in half the words). Lead with Why, not What. Name the concrete outcome, not the capability. Replace adjectives with proof. Make CTAs outcome-specific. Every sentence adds new information or gets cut. A CTA stays short. When replacing AI-isms, rewrite the sentence; do not swap the flagged word for a synonym. Done when: every flagged section is rewritten with the same meaning in fewer words, leading with Why and naming concrete outcomes.
8. Output before/after diff. For each flagged section, show the original, the labels, the rewritten text, and one sentence explaining the change. End with a summary: issue count, top pattern, and confidence (note if copy context was limited). Verify each "After" line: leads with Why, names a concrete outcome, no banned word, no em dash or stand-in, and every fact, number, and link from the "Before" still present. Then apply the leave-it-alone test: every change must fix a named failure from the audit; if it is merely different, restore the original. Done when: a before/after diff is output for each flagged section with labels, rationale, and a summary, and every "After" line passes verification.

Mode cta: end-of-article call-to-action

The archetype decision tree, the exact recommendation structure, and the operating principles live in references/cta-playbook.md.

1. Interview. Ask the five inputs in order, one at a time with 2-4 tappable options, skipping any already supplied; fall back to free text only when the answer cannot be enumerated. (1) Article context: personal or independent blog or essay, newsletter or paid publication, brand or company content-marketing blog, other. (2) Primary objective: newsletter or email subscription, social follow, lead generation (gated asset), product or service signup or free trial, demo or sales call booking, direct purchase, community join, engagement (reply, comment, share), reader support (paid sub or tip), try-it or direct action, other; if the user lists more than one, ask which is primary, because choosing multiple objectives is the dominant cause of CTA failure. (3) Audience and relationship: first-time visitor, returning reader not subscribed, existing subscriber or customer, mixed or unknown. (4) Funnel stage: TOFU (discovery, no buying intent), MOFU (evaluating, comparing), BOFU (ready to act), not applicable. (5) Mechanism preference, asked only if a mechanism could legitimately help (for skeptical or repeat-reader audiences default to none or value-only without asking): none or value-only, curiosity gap, reciprocity (free asset first), discount or offer, urgency (real deadline), scarcity or FOMO, social proof. Capture volunteered constraints (length limit, brand voice, no popups, language, formality). Done when: all five inputs are collected or reported missing.
2. Diagnose. Map the inputs to one archetype via the decision tree in references/cta-playbook.md. Done when: the inputs are mapped to one archetype.
3. Compose the recommendation in the exact structure given in references/cta-playbook.md: archetype with rationale, content copy (headline, body, button, risk reversal), form (placement, visual weight, layout, proof), mechanism, A/B test plan, and a WCAG 2.2 accessibility check. Done when: the recommendation is composed in the exact structure with all sections filled.
4. Anti-pattern warnings. After the recommendation, list 2-3 anti-patterns the user is at risk of given their inputs, as a contrarian check. Failure modes to call out by name: multiple competing CTAs, generic "Subscribe for more" or "Learn More", mechanism mismatch (urgency or scarcity where none exists), SaaS landing-page voice on a personal essay, proofless ask, "Book a Demo" on TOFU content, open-ended reply questions on social. Done when: 2-3 anti-patterns are listed as a contrarian check.
5. Enforce the operating principles in references/cta-playbook.md during composition: one primary CTA per post, publication voice, specificity over cleverness, proof co-located with the ask, mechanisms only when the context supports them, and pushback on bad asks. Done when: the operating principles are enforced during composition.
6. Language and style. Adapt copy to the user's stated brand voice, the article's language (never default to English), the publication's existing cadence, and the reader's expertise level. Honor formality cues (tu/vous, du/Sie) and flag the choice. If non-English, translate the content section but keep structure headings in English. Done when: copy is adapted to brand voice, language, cadence, and expertise level with formality cues flagged.
7. Offer next moves. Suggest 2-3 follow-ups: steelman the opposite CTA, a variant for a different audience or platform, or an end-to-end article review for CTA-supporting signals. Done when: 2-3 follow-ups are suggested.

Mode hook: hook, lede, or accroche

A hook's only job is to make the reader want sentence 2, through one of five levers (a strong hook usually pulls two at once): open a gap, break a prediction, drop into a scene, promise a payoff, borrow weight. The five levers in detail, the type-fit table, the 18-hook catalog, the anti-pattern cull, and language handling live in references/hook-catalog.md.

1. Confirm the brief. Ask before generating if a material input field is missing. Done when: the brief is confirmed or missing material fields are requested.
2. Pick 3-4 hooks from the catalog that are genuinely different, different levers, not three flavors of the same technique. Diversification rule: across the options include at minimum one intellectual hook (contrarian, definition reversal, historical analogy, curiosity gap), one sensory hook (in medias res, concrete detail), and one reader-direct hook (conditional, direct problem, promise). Done when: 3-4 genuinely different hooks are selected, each pulling a different lever.
3. Write 2 candidates per hook, specific to the user's article. The two candidates within one hook explore different angles (different anecdote, statistic, or scene), not rewordings of each other. Done when: 2 candidates per hook are written, each exploring a different angle.
4. Apply the quality gates to every candidate: specific beats abstract (replace "many companies" with "Stripe, Shopify, Vercel"; replace "recently" with a date; replace "studies show" with the actual finding or cut the claim); the first sentence must force the second (read each candidate cold; if sentence 2 would not be clicked after sentence 1, rewrite); match technique to article type using the type-fit table. Done when: every candidate passes the quality gates.
5. Run the anti-pattern cull on every candidate. If a candidate matches any entry, rewrite it before presenting. Done when: every candidate passes the cull or is rewritten.
6. Present and let the user pick. Present using the Output format, ask the user through the question tool, and wait. Do not pick for them. Done when: options are presented and the user is asked to pick.
7. Name the commitment. After the pick, name what the choice commits the rest of the article to. A contrarian hook commits paragraphs 2-3 to defending the non-consensus claim. A scene opener commits the next section to resolving or productively delaying the scene. Done when: the chosen hook's opening commitments are named in one sentence.

UI state copy rules (for product-state strings and the [STATE-COPY] label)