copywriting git:20260902.1fe14a3A

Immutable. This exact content is served forever at /api/v1/blob/441a90ef3b2ed849.

---
name: copywriting
description: 'Use when asked to write or fix product/marketing copy, landing pages, CTAs, UI strings, brand voice, or remove AI writing tells. Not for end-of-article CTA design — use copywriting-cta; not for hooks — use copywriting-hooks.'
---

# Copywriting

## Contract

| Field | Bound contract |
|---|---|
| Trigger | Write product copy, marketing copy, remove AI-isms, landing page copy, brand voice, changelog |
| Authority | Reversible local write; produces or edits user-facing copy and brand voice outputs in the working tree |
| Side effect | Creates or edits copy files and brand voice outputs; no publish, deploy, credential, or remote mutation |
| Done | Copy is free of AI-isms, matches the voice chart, and fits the page type |

## Inputs

- **Copy to fix (Mode B), or a page type and goal (Mode A).** Select Mode B when copy exists or the user pasted it. Select Mode A when nothing is written yet. For a genuinely ambiguous request ("improve this" with no copy in scope), ask one question, then commit.
- 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 one of two modes. Do not ask which mode; infer it from whether copy is in scope.

### Mode A: 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 B: 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.

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

- Destructive CTAs (`rule/destructive-names-action`, `rule/no-confirm-ok-labels`): Verb plus Noun naming the exact object ("Delete project", not "Confirm" or "OK"). Never label a consequential action Confirm, OK, Yes, or a bare verb.
- Canonical verbs (`rule/canonical-verb`): one verb per operation, used consistently; pick the verb whose consequence matches (Delete = permanent, Remove = detach without destroying, Archive = reversibly hide, Discard = drop unsaved edits, Cancel = abandon an in-progress action).
- Error (`rule/error-states-recovery`): state what happened, why when known, and the recovery action; never raw exceptions or a bare "Something went wrong". Separate field-level from surface-level errors; preserve everything the user typed.
- Success (`rule/success-state-specific`): confirm in past tense what happened to which object, proportional to the action.
- Empty (`rule/empty-state-action`): name the object and offer the first action; no dead ends. Three types: never-had-any (guide the first step), filtered-to-zero (clear the filter), user-cleared (confirm completion; the one empty state that needs no CTA).
- Loading (`rule/loading-state-specific`): say what loads and, for long operations, roughly how long; keep the triggering control's label stable.
- Permission (`rule/permission-benefit-first`): state the user benefit before the permission ask; ask in context when the feature is first used.
- Copy without the screen (`rule/reads-without-seeing`): copy must work when heard; field errors read sensibly after their label; link and button text names the destination or action; no directional words ("above", "below", "here").
- Length budgets (size for the tightest surface first; leave 30-40% headroom for translation): button or CTA 2-4 words; title 3-6 words; error message 12-18 words including the recovery step; any sentence the user must act on 14 words (8 reads at full comprehension).

### Banned words

The never-write set, absolute unless a voice file names one as a signature: delve, leverage (verb), robust, seamless, holistic, paradigm, game-changing, cutting-edge, innovative, synergy, revolutionary, effortless, world-class, powerful, showcase, unlock. Also ban **"simple"** as a claim ("our simple onboarding"): never earned upfront, reads as an unkept promise.

### Voice chart structure (when offering to write `VOICE.md`)

Three to five concepts. Each concept has three parts: (1) a brand principle, one word or short phrase; (2) two or three adjectives naming how it shows up in writing; (3) a Do and Don't pair of real interface or page strings. The Don't side is the useful half: make it the plausible near-miss the team actually ships, not a strawman. Start from shipped copy, not brand values. Record locale and spelling convention, house spellings, and any word the brand uses deliberately that a generic list would flag. Name what the voice is not ("Confident, not boastful").

## Failure and recovery
- Invented audience or goal. Copy written without a goal and value proposition reads well and solves the wrong problem. If a context field cannot be settled from files or the user, infer it and name the inference; never present an inference as a fact. Stop and ask only when a wrong guess makes the work useless or unsafe.
- Invented proof. Never fabricate a number, testimonial, or statistic. Use `[PLACEHOLDER: add proof: ...]` and let the user supply it.
- Locale or voice regression. A US-spelling rewrite on an en-AU product ships as a regression across every string it touches. Check existing copy and the voice file before switching spelling or tone; a discovered voice outranks the word lists.
- Point-edit scope creep. Do not turn a named point edit into a page audit; change only the target plus minimum connective tissue.
- Restoration over-reach. Do not rebalance the argument or replace a clear lead with a cleverer one; fix named failures only.
- AI-ism reintroduced or specific dropped. A rewrite that reintroduces an AI tell, or quietly drops a fact, number, or link from the original, is a regression; restore and rewrite again.
- Non-convergent result. If the value proposition cannot be stated in one sentence, the copy is unfixable until it is clarified; report this blocked state with the unresolved value proposition rather than shipping copy that does not serve one.
- Partial results are never presented as done. The done predicate (free of AI-isms, matches the voice, fits the page type) must hold for every line handed back; lines that fail it are rewritten or withheld.

## Output
Return, in order: Mode A brief with marked inferences, 2-3 labeled alternatives, recommendation, edit notes, and pass result; or Mode B before/after diffs with labels, rationale, issue count, top pattern, and confidence; then `VOICE.md` only when offered and accepted.