Copywriting

• IS: short conversion copy (landing pages, hero, subheads, CTAs, product descriptions, onboarding strings, email subjects); product-state strings (destructive CTAs, error, success, empty, loading, permission copy); stripping AI writing tells from any copy.
• IS NOT: long-form articles, posts, or anything written as a person rather than a brand (use the external ghostwriter skill; blog for long-form), slide or deck copy (use presentation-creator), API/product/reference docs (use docs-writing), in-session assistant talk (use eli5), or deciding which action exists, its scope, consequence, reversibility, or reachable states (use product-design; this skill writes final wording once those are decided).

Two modes, auto-detected (do not ask):

• Copy exists or user pasted copy to fix: Mode B (Edit).
• Nothing written yet, or user wants something new: Mode A (Write).
• Genuinely ambiguous ("improve this", no copy in scope): ask one question, then commit.

Reference files

---

Mode A: Writing new copy

Writing progress:
- [ ] Step 1: Gather context
- [ ] Step 2: State the brief, then write
- [ ] Step 3: Discover brand voice
- [ ] Step 4: Choose framework and load references
- [ ] Step 5: Write 2-3 alternatives
- [ ] Step 6: Recommend and explain
- [ ] Step 7: Verify every line before handing back

Step 1: Gather context

Settle all four before writing, from the user or from the files. Where the files do not settle one, infer it and name the inference in Step 2; the failure mode is an invented audience or goal presented as fact.

1. Page purpose. The one action this page drives (sign up, book a demo, download).
2. Audience. The specific reader: job title, pain, what they've already tried.
3. Product. What it does; the concrete user outcome.
4. Traffic source. Where the reader comes from (cold ad, warm email, organic search, referral).

Traffic source sets temperature: cold needs more Why; warm can lead with How or What.

Step 2: State the brief, then write

State the brief and keep going. Mark every field you inferred rather than were told, so the user can correct it against real copy instead of against a question:

Brief:
- Page: [page type]
- Goal: [single action]
- Reader: [specific audience]
- Core outcome: [what changes for the reader]
- Tone: [inferred from brand voice or user-stated]
- Traffic temperature: [cold / warm / hot]

Inferred (correct me): [fields you guessed]

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.

Step 3: Discover brand voice

Find voice signals before inventing one; never default to generic corporate warmth. Work down this order and stop at the first hit:

1. A voice file in the repo: VOICE.md, BRAND.md, docs/voice.md, or a tone-of-voice doc. This is the authoritative source when it exists.
2. The user's own voice, on request only. When the user asks for their voice ("in my voice", "sound like me") and the brand is theirs, read $GHOSTWRITER_HOME/soul.md, falling back to ~/.config/ghostwriter/soul.md. Never apply a personal voice to a client's or employer's brand, and never quote the file back.
3. Existing copy: copy files, README headers, or shipped marketing pages.
4. Inference: B2B SaaS direct and confident, consumer apps warmer, developer tools terse and honest. Ask for brand guidelines alongside the draft, not instead of it.

A discovered voice outranks the word lists. If the voice file or the shipped copy uses a listed word as a signature, keep it; the lists catch generic AI vocabulary, not a deliberate house style. Locale and spelling convention come from the voice too.

Note in the brief which source you used, and mark the voice as inferred when it came from step 4. When no voice file exists and the product will need one, load references/voice-chart.md and offer to write VOICE.md alongside the copy.

Voice is constant, tone adapts. Voice is the brand's personality and does not change between screens. Tone is how that voice meets the reader's state:

Copy that keeps one register across all five reads as robotic in the good moments and cold in the bad ones. 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.

Step 4: Choose framework and load references

Route on what the copy is:

• Product-state copy (error, empty, success, loading, permission) or an action label: load references/ui-states.md and stop here. Persuasion frameworks do not apply to a button that deletes something, and the rest of this step is for marketing surfaces.
• Marketing copy: load references/frameworks.md, plus references/page-types.md when the target is a homepage, landing, pricing, feature, or about page.

Choose the primary framework from the brief:

Layer frameworks freely. Why/How/What almost always applies to hero copy.

Step 5: Write 2-3 alternatives

Write distinct alternatives, labeled Option A, Option B, Option C. Three for a page, hero, or campaign; two for a single string like a CTA or subject line, where a third is padding. One is not a choice, and four is a survey. Each option:

• Apply the chosen framework visibly
• Lead with Why, not What
• Use no banned words (see below)
• Include a headline, subhead, and at least one CTA
• Be structurally different, not the same idea with new adjectives

Step 6: Recommend and explain

Pick one; state which and why in one sentence. For each unpicked option, give one specific edit note: what would make it stronger.

Step 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. Then 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.

---

Mode B: Editing existing copy

Set the edit posture before running the workflow:

• Point edit: The user named one line, word, or section. Read enough surrounding copy to preserve context, change only the target plus the minimum connective tissue, and return the final wording. Do not turn a point edit into a page audit.
• Restoration: The copy already has a clear voice, angle, or opinion. Preserve its vocabulary level, relative emphasis, deliberate omissions, sentence shape, and positioning. Run the workflow to fix specific failures without rebalancing the argument or replacing its lead with a cleverer one.
• Rebuild: The copy is generic, contradictory, or has no discernible perspective. Run the full workflow with latitude to reconstruct it from the brief, but never invent proof.

Editing progress:
- [ ] Step 1: Read all copy-bearing files
- [ ] Step 2: Set the north star
- [ ] Step 3: Audit against persuasion frameworks
- [ ] Step 4: Remove AI writing patterns
- [ ] Step 5: Run seven sweeps
- [ ] Step 6: Flag weakest elements with labels
- [ ] Step 7: Rewrite flagged sections
- [ ] Step 8: Output before/after diff

Step 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 (VOICE.md, BRAND.md, docs/voice.md); it settles the register and locale questions the audit would otherwise guess at, and it overrides the word lists for any word it names as a signature. Where the audit keeps turning on a voice question nobody has answered, load references/voice-chart.md and offer to settle it. Ask which files if unclear; never audit copy you haven't read in context.

Step 2: Set the north star

Write one sentence before auditing: "[User] can now [do X] without [old pain]." Every flag and rewrite serves it. If you can't write it confidently, ask; the copy is unfixable until the value proposition is clear.

Step 3: Audit against persuasion frameworks

Load references/frameworks.md. Check every major copy block against each framework, and carry forward only the highest-impact problems; Step 6 sets the flag budget.

Step 4: Remove AI writing patterns

Load references/word-lists.md and references/ai-patterns.md. Flag each AI-ism with [AI-ISM] plus its pattern type:

• Tier 1 words (word-lists.md): always flag and replace.
• Tier 2 clusters (word-lists.md): flag when 2+ appear in one paragraph.
• Structural patterns (ai-patterns.md): formulaic openings, chatbot artefacts, "let's" transitions, engagement hooks, rhetorical-question openers, significance inflation, copula avoidance, em dashes as ordinary punctuation.
• Drafting tells (ai-patterns.md section 7): prompt echo, a supplied specific swapped for a generic default, uniform confidence. These survive a word-level pass, so check them separately.

Em dashes and their substitutes are Tier 1 tells in their own right; ai-patterns.md section 1 holds the rule and section 8 the P0/P1/P2 triage.

Skip for persuasion-only edits. If the user asked for AI pattern removal, run this first, before the sweeps.

Step 5: Run seven sweeps

Load references/sweeps.md; run all seven in order. Each targets a distinct failure mode; don't skip any because copy "looks fine". Finish with the compound adjective hyphenation pass at the end of that file, and fix what it catches silently rather than flagging it.

Step 6: Flag weakest elements

Attach a label inline to every weak line. Use exactly these labels:

Flag the 3-7 weakest elements, prioritised by impact on conversion or comprehension. Over-flagging is the failure mode here: a list of twenty issues dilutes into one nobody acts on.

Step 7: Rewrite flagged sections

• Cut hard: a block that reads as already-tight usually isn't. Same meaning in half the words.
• Lead with Why (the user's problem or desire), not What (the product).
• Name the concrete outcome, not the capability.
• Replace adjectives with proof: "powerful analytics" becomes "see which pages kill signups".
• Make CTAs outcome-specific: "Start syncing" beats "Get started".
• Every sentence adds new information or gets cut.
• A CTA stays short; it is not the place to explain the feature.
• When replacing AI-isms, rewrite the sentence; don't swap the flagged word for a synonym.

Step 8: Output before/after diff

## Copy Audit: [file or component name]

**North star:** [one-sentence value prop]

---

### [Section name]

**Before:**
> [original text]

**Issues:** `[LABEL]`, `[LABEL]`

**After:**
> [rewritten text]

**Why:** [one sentence explaining the change]

---

### Summary
- N issues flagged across N sections
- Top pattern: [most common label]
- Confidence: [high / medium; note if copy context was limited]

Verify each "After" line before handing back: 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. A rewrite that reintroduces an AI tell, or quietly drops a specific, is a regression. 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.

---

Banned words

The never-write set. Applies in both modes, so it lives here rather than behind a reference load:

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.

A voice file that names one of these as a signature word is the only thing that overrides the list (Step 3). Absent that, treat it as absolute.

references/word-lists.md holds the wider tiered AI vocabulary with replacements; that list is for detection in Edit mode, not a second copy of this one.

---

Gotchas

• State the brief before writing and mark what you inferred: copy written without a goal and value proposition reads well and solves the wrong problem.
• Read copy in context before judging; a vague-looking line may carry contrast with adjacent copy.
• frameworks.md lists unearned adjectives (powerful, seamless, robust) that also sit in the banned words and in word-lists.md. One occurrence is one flag; don't stack [TELL-NOT-SHOW] and [AI-ISM] on the same word.
• The personal voice lookup in Step 3 is opt-in and read-only. Reading soul.md does not make this the skill for personal messages, posts, or long-form; those stay with ghostwriter. Never copy its contents into a repo, a brief, or the output.
• Preserve the project's locale and brand voice; check existing copy before switching spelling or tone. A US-spelling rewrite on an en-AU product ships as a regression across every string it touches.

---

Skill handoffs

Taste Training (blode.co/taste-training) trains the eye these rules encode, across type, copy, craft, interaction, and motion.

---

Supporting file: references/ai-patterns.md

AI writing patterns: detection and fixes

Table of contents

1. Formatting (#1-formatting)
2. Sentence structure (#2-sentence-structure)
3. Template phrases (#3-template-phrases)
4. Transition phrases (#4-transition-phrases)
5. Structural issues (#5-structural-issues)
6. Chatbot artefacts (#6-chatbot-artefacts)
7. Drafting tells (#7-drafting-tells)
8. Severity tiers (#8-severity-tiers)

---

1. Formatting

Em dashes

Zero, in headings and body copy alike. Replace with a comma, colon, full stop, parentheses, or two sentences; a colon is the usual fix when the dash introduced an elaboration. Catch U+2014, the double-hyphen substitute (--), and a spaced hyphen standing in for one (-). Copy is short enough that any allowance is meaningless, so treat a single occurrence as a failure rather than a frequency to manage.

Bold labels

A bold label takes a colon, not a period: **Pricing:**, never **Pricing.**. The period version is a formatting tell that survives most edits because it looks deliberate.

Bold overuse

Strip bold from most phrases. Max one bolded phrase per major section, ideally none. If something is important enough to bold, restructure the sentence to lead with it instead.

Emoji in headers

Remove entirely. No ## 🚀 What This Means. Social posts may use one or two sparingly, at line end, never mid-sentence.

Excessive bullet lists

Convert bullet-heavy sections into prose paragraphs. Bullets only for genuinely list-like content: feature comparisons, step-by-step instructions, API parameters. If a bullet list has a repeating bold header per item, strip the headers and write as prose.

---

2. Sentence structure

Hollow intensifiers

Cut: genuinely, truly, quite frankly, to be honest, let's be clear, it's worth noting that, real (as in "a real improvement"). Just state the fact.

Vague endorsement ("worth [verb]-ing")

Cut: worth reading, worth paying attention to, worth a look, worth exploring, worth checking out. These swap a generic thumbs-up for a specific reason. Say why something matters instead.

Hedging

Cut: perhaps, could potentially, it's important to note that, to be clear. Make the point directly. Don't stack them either ("could potentially eventually").

Announced honesty

Cut: "honestly", "to be honest", "one honest note", "I'll be straight with you". Labelling one line as the honest one implies the rest isn't. Delete the label and keep the line.

Emotional flatline

Cut: "what struck me was", "I couldn't help but notice", "it's fascinating that". These narrate a reaction instead of giving the reader the thing that caused it. State the thing.

"It's not X, it's Y"

Max one per piece, only if it serves the argument. Rewrite as a direct positive statement.

Compulsive rule of three

Vary groupings: two items, four, or a full sentence instead of triads. Max one "adjective, adjective, and adjective" per piece.

Missing connective tissue

Each paragraph connects to the last. If they could be rearranged unnoticed, add a bridge sentence.

---

3. Template phrases

Slot-fill constructions that signal a sentence was generated, not written:

• "a [adjective] step towards [adjective] AI infrastructure" → describe the specific capability or outcome
• "a [adjective] step forward for [noun]" → say what actually changed
• "Whether you're [X] or [Y]" → false breadth. Pick the audience you're writing for, or cut
• "I recently had the pleasure of [verb]-ing" → say what happened: "I talked to," "I read," "I attended"
• "In today's [X]" / "In an era where" → cut or state specific context
• "When it comes to" → talk about the thing directly

---

4. Transition phrases

Remove or rewrite these:

• "Moreover" / "Furthermore" / "Additionally" → make the connection obvious, or use "and," "also," "on top of that"
• "It's worth noting that" / "Notably" → just state the fact
• "Here's what's interesting" / "Here's what caught my eye" → let content signal its own importance. If you need a lead-in, make it specific: "The revenue number matters because..."
• "In conclusion" / "In summary" / "To summarise" → the conclusion should be obvious without the label
• "At the end of the day" → cut
• "That said" / "That being said" → cut, or use "but," "yet," "however" (don't overuse any one)

---

5. Structural issues

Uniform paragraph length

If every paragraph is roughly the same size, vary deliberately: some one sentence, some longer.

Formulaic openings

If it opens with broad context before the point ("In the rapidly evolving world of..."), lead with the news or insight instead. Context comes second.

Rhetorical-question openers

"So why should you care?", "What does this mean for your team?", "Sound familiar?" Questions the reader didn't ask, answered by the writer. Delete the question and open with the answer.

Engagement hooks

"Here's the thing.", "The kicker?", "Plot twist:", "But here's where it gets interesting." A tee-up that promises significance the next sentence has to deliver anyway. Cut the tee-up and state the thing; if the thing is interesting, it survives without the label.

Copula avoidance

AI avoids "is" and "has" with fancier verbs: "serves as," "features," "boasts," "presents," "represents." Reads like a press release. Default to "is" or "has" unless a specific verb adds real meaning.

Synonym cycling

AI rotates synonyms to avoid repeating a word: "developers… engineers… practitioners… builders" in one paragraph. Humans repeat the clearest word. If the noun appears three times and it's right, keep all three.

Vague attributions

"Experts believe," "Studies show," "Research suggests" without naming the expert, study, or source. Cite a specific source, or drop the attribution and state the claim directly.

Significance inflation

"Marking a pivotal moment in the evolution of..." or "a watershed moment for the industry" inflate routine events. State what happened. Let the reader judge significance.

False ranges

AI fakes breadth by pairing unrelated extremes: "from the Big Bang to dark matter," "from ancient civilisations to modern startups." Sound sweeping but say nothing. List the actual topics, or pick the one that matters.

---

6. Chatbot artefacts

Remove entirely from published prose:

• "I hope this helps!", "Certainly!", "Absolutely!", "Great question!", "Feel free to reach out", "Let me know if you need anything else"
• "In this article, we will explore…" or "Let's dive in!" → cut, or open directly
• "Let's explore," "Let's take a look," "Let's break this down" → any "let's + verb" used as a transition, not a genuine invitation. Start with the point
• "Let me think step by step," "Breaking this down," "To approach this systematically," "Step 1:" → chain-of-thought leaking into prose. State the conclusion, then the evidence
• Acknowledgement loops: "You're asking about," "To answer your question," "That's a great question. The..." → just answer
• Sycophantic openers: "Great question!", "Excellent point!", "You're absolutely right!" → remove entirely

---

7. Drafting tells

These don't show up as a bad phrase on the page. They show up as copy that is competent and still reads as generated, so they survive every word-level pass.

Prompt echo

The draft reuses the brief's own phrasing. Asked for copy about "a unified workspace for distributed teams", it returns a headline about a unified workspace for distributed teams. Take the facts from the brief, throw away its wording, and say it the way the brand says things. This is the single biggest tell in copy that otherwise passes every other check here.

Generic default over the supplied specific

The brief gives a real number, name, integration, or price, and the draft ships the category-standard placeholder instead ("thousands of teams" over the supplied 4,200; "your favourite tools" over the supplied Slack and Linear). Every specific the user supplied appears in the copy, or it was cut for a stated reason.

Uniform confidence

Every line lands at the same pitch, usually mid-enthusiasm. Real copy has a flat line next to a strong one. If no sentence is plainer than the ones around it, the emphasis is doing nothing.

---

8. Severity tiers

Prioritise fixes when time is limited.

P0: credibility killers (fix immediately)

• Cutoff disclaimers: "As of my last update," "I don't have access to real-time data"
• Chatbot artefacts: "I hope this helps!", "Great question!"
• Vague attributions without named sources: "Experts believe"
• Significance inflation on routine events: "a watershed moment for the industry"
• A specific the user supplied (number, name, price, integration) replaced by a generic default

P1: obvious AI smell (fix before publishing)

• Prompt echo: the copy hands the brief's own wording back
• Tier 1 word violations (delve, leverage, robust, seamless, etc.)
• Template phrases and slot-fill constructions
• "Let's" transition openers
• Formulaic openings ("In the rapidly evolving world of...")
• Engagement hooks and rhetorical-question openers
• Bold overuse
• Any em dash, --, or spaced hyphen standing in for one

P2: stylistic polish (fix when time allows)

• Generic conclusions ("The future looks bright", "Only time will tell")
• Compulsive rule of three
• Uniform paragraph length and uniform confidence
• Announced honesty and emotional flatline
• Bold labels closed with a period instead of a colon
• Copula avoidance (serves as, features, boasts)
• Overused transition phrases (Moreover, Furthermore, Additionally)
• Tier 2 word clusters in the same paragraph

Quick triage rule: For a fast pass, fix P0 and P1 only. A clean P0+P1 pass is publishable. P2 is polish.

---

Supporting file: references/frameworks.md

Persuasion Frameworks

Apply each framework to the copy under review.

Table of contents

• Why/How/What (Simon Sinek) (#whyhowwhat-simon-sinek)
• PAS (Problem → Agitate → Solution) (#pas-problem--agitate--solution)
• AIDA (Attention → Interest → Desire → Action) (#aida-attention--interest--desire--action)
• StoryBrand (#storybrand)
• BAB (Before → After → Bridge) (#bab-before--after--bridge)
• Show don't tell (#show-dont-tell)
• Benefit not feature (#benefit-not-feature)
• Sentence economy (#sentence-economy)
• CTA clarity (#cta-clarity)

---

Why/How/What (Simon Sinek)

Most product copy starts with What (the product) or How (the mechanism). Start with Why (the user's motivation or felt problem).

Test: Does the first hero/README sentence explain what the product is, or why someone would want it?

Correct order: Why → How → What.

Before (wrong order):

"StrataSync is a real-time data sync engine for React apps. It uses WebSocket connections to keep your data current. Never deal with stale dashboards again."

After (Why first):

"Stale dashboards kill trust. StrataSync keeps every client in sync automatically. No polling, no refresh buttons."

Flag as: [WHAT-NOT-WHY]

---

PAS (Problem → Agitate → Solution)

Name the pain, amplify the cost of ignoring it, then present the solution.

Best for: Problem-aware audiences. Long-form landing pages, email, ad copy.

Template:

1. Problem. The pain the user recognises.
2. Agitate. The consequences, made real and urgent.
3. Solution. How the product resolves it cleanly.

Example (developer tool):

Problem: Your API keys are scattered across .env files, CI configs, and Slack messages. Agitate: One leaked key can bring down production, and you won't know until a customer calls. Solution: Vault centralises every secret with per-environment rotation and zero-config CI integration.

Flag: No flag. PAS is a structural choice, not an error pattern.

---

AIDA (Attention → Interest → Desire → Action)

A sequential funnel moving a cold reader from awareness to click. Each stage earns the next.

Best for: Cold traffic: ads, cold email, splash pages with no prior context.

Template:

1. Attention. Interrupt the scroll: a bold claim, question, or specific fact.
2. Interest. Why it's relevant to them specifically.
3. Desire. The outcome they want, via social proof or concrete results.
4. Action. One clear CTA matching the desire just created.

Example (B2B SaaS):

Attention: "73% of SaaS churn happens before users hit their first 'aha' moment." Interest: "If your onboarding takes more than one session, you're already losing." Desire: "Teams using Onramp reduce time-to-value by 40%, measured from signup to first export." Action: "See your onboarding score free →"

Flag: No flag. AIDA is a structural choice. Flag individual components with [WHAT-NOT-WHY], [TELL-NOT-SHOW], or [WEAK-CTA].

---

StoryBrand

The customer is the hero; the product is the guide. The guide gives the hero a plan and a CTA that leads to success and away from failure.

Key rule: Never make the product the hero. A guide who centres themselves loses the customer's trust.

The 7 parts:

Before (product as hero):

"We built Relayer after years of fighting broken CI pipelines. Our team is obsessed with developer experience."

After (customer as hero):

"You shouldn't have to babysit your pipeline. Relayer watches it for you, so you can ship and move on."

Flag: [WHAT-NOT-WHY] when the product, not the customer, is centred.

---

BAB (Before → After → Bridge)

Paint the current painful state, show the desired future state, then explain how the product bridges them.

Template:

1. Before. The frustration or friction the user recognises right now.
2. After. The world as they want it to be.
3. Bridge. How the product creates that transition.

Example (analytics tool):

Before: You spend two hours every Monday pulling reports from four different tools before you can answer one question. After: Every metric you care about, live, in one dashboard. Monday starts with decisions, not data wrangling. Bridge: Metric pairs your existing stack in 15 minutes and surfaces the numbers that actually move revenue.

When to use over PAS: BAB is warmer and aspirational; PAS is confrontational. Use BAB when the audience is motivated but stuck, PAS when they're not yet urgent.

---

Show don't tell

Adjectives claim; specifics prove.

Test: Can the adjective be replaced with a specific fact, number, or scenario?

Unearned adjectives, flag every instance in hero copy. Each claims a quality the reader has no reason to believe yet:

• powerful, simple, easy, seamless, beautiful, robust, flexible, scalable, smart, intuitive, modern, next-generation, cutting-edge, best-in-class

Rule: If you can't name the outcome, the claim doesn't belong in the hero.

Flag as: [TELL-NOT-SHOW]

---

Benefit not feature

Features describe the product; benefits, what changes for the user; outcomes, the life after the change.

Test: Does this sentence describe what the product has or what the user gets?

Feature → Benefit → Outcome chain:

Before (feature):

"Automated changelog generation with semantic versioning support."

After (benefit → outcome):

"Ship without writing release notes. Your changelog writes itself."

Rule: Lead with the outcome for the user; mention the mechanism only after the benefit is clear. Never lead with "featuring" or "with built-in".

Flag as: [FEATURE-NOT-BENEFIT]

---

Sentence economy

Every sentence must earn its space.

Tests:

• Remove the sentence: does the meaning change? If not, cut it.
• Does the opener add anything? "In order to", "It is important to note that", "The fact is": cut the opener.
• Over 25 words? Break it at the strongest claim.
• Does it restate the headline? Cut it.

Dead-weight patterns:

Before:

"We believe that developers deserve better tooling. Whether you're a solo founder or a team of 50, Relay is designed to make deployment simple and powerful."

After:

"Deploy in one command. Roll back in two seconds."

Flag as: [DEAD-WEIGHT]

---

CTA clarity

CTAs fail when they describe the action, not the outcome. A CTA answers: what do I get, what am I committing to?

Formula: Action verb + what they get + qualifier (optional).

Test: If someone reads only the CTA, do they know what they're committing to?

Rules:

• Use a verb that names the outcome: Start, Create, See, Download, Get, Book, Claim.
• Add a qualifier when space allows: "free", "in 5 minutes", "no card", "no install".
• Never use two CTAs with the same verb on the same screen.
• Primary CTA is high-commitment (Start, Create, Buy); secondary is low-commitment (See, Watch, Learn).

Flag as: [WEAK-CTA]

---

Supporting file: references/page-types.md

Page Types

Structure, norms, and gotchas for the five common marketing page types.

Table of contents

• Homepage (#homepage)
• Landing page (#landing-page)
• Pricing page (#pricing-page)
• Feature page (#feature-page)
• About page (#about-page)

---

Homepage

Purpose: Establish what the product is and who it's for. Serve the primary segment without going so generic it serves no one.

Primary challenge: Many segments visit; writing for everyone resonates with no one. Pick the highest-value segment, write for them directly.

Recommended framework: Why/How/What (Simon Sinek) or StoryBrand

Required sections (in order):

Gotcha: Don't add a secondary CTA ("or watch a video") that dilutes the primary action. If you must, make the primary CTA visually dominant 3:1.

---

Landing page

Purpose: Drive a single action from a specific traffic source. Message must match what brought the reader (ad, email, link).

Primary challenge: Message match. If the ad said "Cut your AWS bill in half" and the page opens "Welcome to CloudSave", you've lost them. The headline must mirror the promise that brought them.

Recommended framework:

• PAS for problem-aware traffic (know the problem, need convincing your solution fits)
• AIDA for cold traffic (saw an ad, no context)

Required sections (in order):

Gotcha: One CTA only. Strip navigation, footer links, and anything that lets visitors leave without converting. Every non-converting element is friction.

---

Pricing page

Purpose: Help visitors choose the right plan. Reduce "which one is right for me?" anxiety.

Primary challenge: Decision paralysis. Too many options, unclear differentiation, or plans named by tier ("Basic/Pro/Enterprise") instead of by buyer type.

Recommended framework: BAB (Before = confusion, After = confident choice, Bridge = clear plan structure)

Required sections (in order):

Gotcha: Name plans for the buyer type, not the tier. "Starter/Growth/Scale" beats "Basic/Pro/Enterprise": it helps visitors self-select rather than guess.

---

Feature page

Purpose: Connect a feature to a customer outcome. Create a clear path to try or buy.

Primary challenge: Feature pages default to listing capabilities instead of naming outcomes. Visitors here are already interested; they want to know if this feature solves their specific problem.

Recommended framework: Feature → Benefit → Outcome chain

Feature: [what the product does]
     ↓
Benefit: [what changes for the user]
     ↓
Outcome: [specific, measurable result]

Required sections (in order):

Gotcha: Feature pages are for people already evaluating the product. Skip the broad "here's why X matters" setup; go straight to the specific outcome this feature delivers.

---

About page

Purpose: Build trust, show the humans behind the product, tie the brand's origin to a customer benefit.

Primary challenge: About pages turn inward. Companies write about themselves (founding year, team size, mission) without explaining why it matters to the reader. Every element must pass the "so what does this mean for me?" test.

Recommended framework: StoryBrand (brand as guide, customer as hero, even here)

Required sections (in order):

Gotcha: The about page is not a resume. Every paragraph should answer "so what does this mean for me?" If the answer is "nothing", cut it.

Example reframe:

---

Supporting file: references/sweeps.md

Seven-Sweep Editing Framework

Structured audit for existing copy. Run sweeps in order, one at a time.

Table of contents

• How to use this framework (#how-to-use-this-framework)
• Sweep 1: clarity (#sweep-1-clarity)
• Sweep 2: voice and tone (#sweep-2-voice-and-tone)
• Sweep 3: so what (#sweep-3-so-what)
• Sweep 4: prove it (#sweep-4-prove-it)
• Sweep 5: specificity (#sweep-5-specificity)
• Sweep 6: emotion (#sweep-6-emotion)
• Sweep 7: zero risk (#sweep-7-zero-risk)
• Quick-pass editing checks (#quick-pass-editing-checks)
• Compound adjective hyphenation (#compound-adjective-hyphenation)

---

How to use this framework

1. Work sweeps in sequence; each builds on the last.
2. Flag issues with the inline tags per sweep (e.g. [VAGUE], [NO-PROOF]).
3. Flag everything before fixing, to prevent scope creep.
4. After all seven sweeps, resolve every flag before publishing.

---

Sweep 1: clarity

Focus: Comprehension. Reader never re-reads a sentence.

Check for:

• Confusing structure (nested clauses, stacked passive voice)
• Unclear pronouns ("it", "they", "this" with ambiguous antecedents)
• Undefined jargon or acronyms
• Claims readable two ways
• Context the writer assumed

Flags: [JARGON] (needs definition or replacement), [VAGUE] (could mean multiple things)

Example fix:

• Before: "It integrates with the tools your team already uses to streamline it."
• After: "The app connects to Slack, Notion, and Google Drive. No new workflows required."

---

Sweep 2: voice and tone

Focus: Consistency. Copy reads as one person with a stable personality.

Watch for:

• Formal/casual shifts in one section ("utilise" then "use")
• Brand personality inconsistencies (playful headline, stiff body)
• Tense changes without narrative reason
• Mismatched register (technical then colloquial)

Action: Identify the dominant voice, standardise to it. Don't average; pick one and commit.

Voice, not tone. Tone is meant to shift with the reader's state: brisk on a routine save, careful before a deletion. That is not drift. Flag the line where the copy reads as a different brand, not the line where the same brand meets a different moment. The tone table in SKILL.md Step 3 sets the expected shifts.

Flag: [VOICE-DRIFT] on the line that breaks from the dominant voice, not on the voice you decided to keep.

The test: Read the section as one speaker. If two people seem to be talking, the second one is the flag. For each drifting line, ask "how would a confident human say this?" and rewrite that way.

Common mismatches:

• Marketing page enthusiastic; product description reads like a manual
• Hero uses "you"; about page switches to "our customers"
• Email subject punchy; body formal and slow
• Corporate register ("leverage", "synergise", "solution-oriented") next to plain sentences

---

Sweep 3: so what

Focus: Every claim answers "why should the reader care?"

The test: Ask "so what?" of each sentence; if you can't answer, it failed.

Flags: [DEAD-WEIGHT] (no reader value), [FEATURE-NOT-BENEFIT] (what the product does, not what it does for the reader)

Examples:

• Feature: "Automatic daily backups." → [FEATURE-NOT-BENEFIT]
• Benefit: "Your data is safe even if your laptop dies tonight."
• Dead weight: "We are committed to excellence in everything we do." → [DEAD-WEIGHT]

Note: Not every sentence must be a direct benefit. Context, transitions, and proof earn their place; flag only what neither informs nor motivates.

---

Sweep 4: prove it

Focus: Back every claim with evidence.

Check for:

• Testimonials from real, named customers
• Case studies with specific outcomes
• Stats, percentages, timeframes, hard numbers
• Third-party validation (awards, press, certifications, analyst reports)
• Guarantees or risk-reversal offers that show confidence

Flag: [NO-PROOF] on any strong assertion without support.

Placeholder: [PLACEHOLDER: add proof: stat / testimonial / example]

Claims that need proof:

• "Trusted by thousands of teams worldwide." → [NO-PROOF] → [PLACEHOLDER: add proof: exact customer count or named logos]
• "The fastest solution on the market." → [NO-PROOF] → [PLACEHOLDER: add proof: benchmark stat or third-party comparison]
• "Our customers see results immediately." → [NO-PROOF] → [PLACEHOLDER: add proof: testimonial with timeframe]

---

Sweep 5: specificity

Focus: Replace vague language with concrete detail.

Check for:

• Vague time ("quickly", "fast", "soon")
• Vague quantity ("many", "several", "a lot")
• Vague outcome ("better results", "improved performance", "saves time")
• Named outcomes without named contexts (who achieves what, under what conditions)

Flag: [VAGUE] on anything that could be more concrete.

Transformations:

• "Saves time" → "Cuts weekly reporting from 4 hours to 15 minutes"
• "Used by many companies" → "Used by 4,200 teams across 60 countries"
• "Improves team performance" → "Teams close 30% more tickets per sprint after the first month"
• "Easy to set up" → "Most teams are live in under 20 minutes"
• "Affordable pricing" → "Plans start at $12 per user per month"

Note: If the number isn't known, use the [PLACEHOLDER] pattern from Sweep 4 rather than leaving vague language in place.

---

Sweep 6: emotion

Focus: Name the pain the reader already feels before selling the outcome. Readers act once they feel understood, so pain acknowledgment usually outperforms one more benefit statement.

Flag: [PAIN-NOT-NAMED] on a section that states benefits without ever naming the frustration the reader arrived with.

The test: Point at the exact line where the reader thinks "yes, that's exactly my problem". If the section has no such line, flag it. If it has three, the copy is wallowing; cut to one.

Check for:

• Pain named in the reader's own words, not abstracted ("teams struggle with alignment")
• Aspirational outcomes concrete enough to picture
• Movement from problem to possibility, not benefits listed flat

Guidance:

• Don't manufacture emotion; forced enthusiasm reads as inauthentic and is the default failure here.
• Mirror the reader's actual state at this point in the page; a pricing page reader is further along than an ad reader.

---

Sweep 7: zero risk

Focus: Remove friction at and near CTAs. The next step should feel costless.

Check for:

• Objections not addressed before the CTA
• Missing trust signals (security badges, customer logos, review counts)
• Unclear next step: what happens when I click?
• Missing risk reversal: free trial, money-back guarantee, no-credit-card-required, cancel-anytime

Flag: [WEAK-CTA] on any CTA standing alone without a qualifier or trust signal.

Examples:

• Weak: "Sign up now."
• Stronger: "Start free. No credit card required."
• Stronger still: "Start your 14-day free trial. Cancel anytime. No card needed."

CTA qualifier checklist:

• What does the reader get immediately?
• Time or money commitment?
• What if they change their mind?
• Is the next step one plain sentence?

---

Quick-pass editing checks

Apply at the end of all seven sweeps as a final line-level pass.

Cut these words on sight; they rarely add meaning:

• "very", "really", "truly", "highly"
• "just", "simply", "easily"
• "actually", "basically", "essentially"
• "things", "stuff", "aspects", "elements"

Test: Remove the word. If the sentence still means the same, cut it.

Paragraph length: 2 to 4 sentences is the web-copy norm, but vary it deliberately and use 1-sentence paragraphs for emphasis. Uniform paragraph length is itself an AI tell; see ai-patterns.md section 5.

---

Compound adjective hyphenation

Mechanical, high-frequency, and invisible to a persuasion pass. The rule turns on one question: does the multi-word modifier sit before the noun it describes?

Before the noun, hyphenate. Most often number plus unit.

Standing alone as a noun phrase, no hyphen. Usually after a verb or a preposition.

Template variables follow the same rule. The hyphen goes between the variable and the unit, which is the case teams get wrong most often because the variable hides the pattern.

Decision: is a noun coming next, and does the modifier describe it? Hyphenate. Otherwise leave it open. Never hyphenate an adverb ending in -ly: "a fully managed service", not "a fully-managed service".

Fix these silently in a rewrite. They don't earn a flag of their own unless the same error repeats across a surface, which makes it a style decision worth naming.

---

Supporting file: references/ui-states.md

UI State Copy

Read when naming actions or writing destructive CTAs, error, success, empty, loading, or permission copy. Product-state copy, not marketing: words a user reads while doing a task, where clarity about object, scope, and consequence beats persuasion.

Defines stable rule IDs that product-design cites when routing naming and state decisions here. Keep IDs exactly as written.

Contents

• Destructive CTAs and action labels
• Canonical product verbs
• Error-state copy
• Success-state copy
• Empty-state copy
• Loading-state copy
• Permission-request copy
• Copy without the screen
• Length budgets
• Rule IDs

Destructive CTAs and action labels

rule/destructive-names-action

Destructive and primary CTAs use Verb plus Noun naming the exact object, so the button says what it does.

A label that omits the object forces users to reconstruct the consequence from surrounding text they often skip.

rule/no-confirm-ok-labels

Never label a destructive or consequential action Confirm, OK, Yes, or a bare verb; these hide what happens. Exception: a purely informational dialog with one dismiss action and no consequence, where Got it or Close is fine.

Canonical product verbs

rule/canonical-verb

One verb per operation, used consistently. Don't call the same operation "Delete" on one screen and "Remove" on another. The verb carries the consequence, so the wrong verb misleads.

When two verbs fit, pick the one whose consequence matches, then use it everywhere for that action.

Error-state copy

rule/error-states-recovery

An error states three things: what happened, why (when known), and the recovery action. Never show raw exception or stack text, never a bare "Something went wrong" with no next step.

Separate field-level errors (fix this input, shown inline) from surface-level errors (action failed, shown near the action). Preserve everything the user typed; never clear the form on a failed submit.

Success-state copy

rule/success-state-specific

Confirm in past tense what happened to which object, proportional to the action. Add follow-on information only when it changes what the user does next.

Match weight to stakes: a routine save earns two words; a milestone can carry one sentence about what happens next.

Empty-state copy

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), and user-cleared (confirm completion and say when new content appears; the one empty state that needs no CTA).

Often a first impression. Treat it as onboarding, not an error.

Loading-state copy

rule/loading-state-specific

Prefer specific copy over bare "Loading..." when the target is known. Say what loads, and for long operations, roughly how long.

Keep the triggering control's label stable while busy; use its loading affordance instead of swapping text, so the layout doesn't jump and the user still sees which action is in flight.

Permission-request copy

rule/permission-benefit-first

State the user benefit before the permission ask; never lead with the system need. Pattern: benefit, then permission.

Ask in context, when the feature is first used, not at launch.

Copy without the screen

rule/reads-without-seeing

Copy must work when heard, not seen.

• A field error reads sensibly after its label: screen readers announce "Email address, must include @", so Must include @ works and Invalid does not.
• Link and button text names the destination or action: View pricing, never Click here or a bare Learn more.
• No directional words ("above", "below", "here"): position changes across screen sizes and means nothing read aloud. Name the place instead ("in Settings", "on the previous step").

Length budgets

Ceilings for UI strings. Size copy for the tightest surface (usually mobile) first.

Leave 30 to 40% width headroom for translation; German and French run that much longer than English.

Rule IDs

Shared vocabulary with product-design, which cites them when routing naming and state decisions here:

• rule/destructive-names-action
• rule/no-confirm-ok-labels
• rule/canonical-verb
• rule/error-states-recovery
• rule/success-state-specific
• rule/empty-state-action
• rule/loading-state-specific
• rule/permission-benefit-first
• rule/reads-without-seeing

Flag violations of these in edit mode with the [STATE-COPY] label.

---

Supporting file: references/voice-chart.md

Voice chart

Read when a product has no voice file and needs one, or when an existing one is a list of adjectives nobody can apply. A voice chart is the artefact that makes brand voice usable: it turns "friendly and confident" into copy a writer can check a line against.

Output it as VOICE.md at the repo root, where the copy work will find it next time.

Structure

Three to five concepts. Fewer than three is not a voice, more than five is not memorable. Each concept has three parts, and the third is the one that does the work:

1. Concept. A brand principle, one word or a short phrase.
2. Characteristics. Two or three adjectives naming how the concept shows up in writing.
3. Do and don't. Real interface or page strings, in pairs. Abstract description is not a substitute; a writer settles an argument by pointing at a pair.

The don't side is the useful half. A don't that no reasonable writer would produce ("Don't be rude to users") teaches nothing. Make it the plausible near-miss that the team actually ships.

Template

## Concept: [principle]

**Characteristics:** [adjective], [adjective], [adjective]

**What this means:** [one or two sentences on how it changes the writing]

**Do**
- "[real string]"
- "[real string]"

**Don't**
- "[the plausible near-miss]"
- "[the plausible near-miss]"

Worked example

Concept: Direct

Characteristics: plain, front-loaded, unhedged

What this means: the reader gets the outcome in the first few words. No preamble, no softening a fact into a suggestion.

Do

• "Your export is ready. It expires in 7 days."
• "This deletes the project and its 40 files."

Don't

• "We wanted to let you know that your export is now available."
• "Please note that this action may affect associated files."

Concept: Specific

Characteristics: concrete, numbered, named

What this means: every claim carries a number, a name, or an example. A sentence that would survive on a competitor's site has not said anything.

Do

• "Cuts weekly reporting from 4 hours to 15 minutes."
• "Connects to Slack, Linear, and GitHub."

Don't

• "Saves your team valuable time."
• "Integrates with the tools you already use."

Filling one in

• Start from shipped copy, not from brand values. Pull twenty real strings, sort them into the ones that feel right and the ones that don't, and name the pattern. Values documents describe the company; the strings describe the voice.
• Write the don't column from the copy that got rewritten in review. That history is where the voice actually lives.
• Record locale and spelling convention (en-AU, en-US), the terms with a house spelling, and any word the brand uses deliberately that a generic word list would flag. That last line prevents an audit stripping a signature word.
• Name what the voice is not. "Confident, not boastful" settles more edits than three more adjectives.
• Revisit it when a rewrite feels wrong but no rule explains why. That gap is a missing concept.

Common characteristics

Pick from these when naming a concept, then make them concrete with pairs:

Warm: friendly, encouraging, welcoming, supportive, human Neutral: clear, direct, practical, matter-of-fact, informative Serious: precise, measured, transparent, respectful, careful Personality: playful, witty, dry, conversational, technical, humble, confident

Adjectives alone are not a voice chart. Two brands claiming "friendly and clear" write nothing alike; the pairs are what distinguish them.

---

Supporting file: references/word-lists.md

Word lists

Table of contents

• Tier 1: always replace (#tier-1-always-replace)
• Tier 2: flag when 2+ appear in the same paragraph (#tier-2-flag-when-2-appear-in-the-same-paragraph)
• Tier 3: flag only at high density (#tier-3-flag-only-at-high-density)

---

A discovered voice file outranks every tier below. When a brand or personal voice file names a word as a signature, keep it and do not flag it; the lists describe generic AI vocabulary, not a house style that deliberately uses one of these words.

---

Tier 1: always replace

5-20x more common in AI text than human writing. Replace on sight.

---

Tier 2: flag when 2+ appear in the same paragraph

One is fine; two or more signals a pattern. Flag and suggest replacements.

---

Tier 3: flag only at high density

Fine in moderation. Flag only at roughly 3%+ density: that signals AI filler, not genuine description.