Content and UX Writing Audit

Product copy is written by many hands over many years: designers labeling buttons in Figma, engineers writing error strings at midnight, marketers naming features, support writing macros. Each string makes sense locally. Together they call the same action three different things and explain the same error five different ways.

Nobody notices because nobody ever reads the copy as a whole. Users do. They learn that the button says Transfer on one screen, then meet Send on the next and wonder if it is a different feature. Drifted copy reads like a product built by strangers, because it was.

An audit is the boring, valuable fix: read everything, compare it against the style guide, and produce a terminology map and a fix list. Reading every string is exactly the kind of exhaustive, low-judgment sweep that agents are good at, and it is the part content designers never get time for.

Run it before a localization push, before a rebrand or voice refresh, after an acquisition or merger of two products, or whenever a content designer joins a product that has never had one. It is also a useful periodic health check, because copy drifts continuously and quietly.

It assumes you have, or are willing to draft, a content style guide. If there is no guide at all, run a lighter version of the audit first to discover the de facto conventions, then write the guide, then audit against it.

• Pre-localization: inconsistent source strings multiply translation cost and error.
• Voice and tone refresh: find every string that contradicts the new voice.
• Post-merger products: two vocabularies need to become one.
• New content designer onboarding: a map of the territory in an afternoon.

This is a subagent fan-out. The product area is split into surfaces — buttons and primary actions, empty states, error messages, onboarding, transactional emails — and each surface gets its own audit agent with the same style guide and the same reporting format. Bounded surfaces keep each agent's reading careful and its findings specific; one agent reading everything gets sloppy by the third screen.

For a single product area, launching the subagents directly from Claude Code is enough. For a sweep across a whole product, run it as a dynamic workflow instead: a JavaScript script Claude writes and runs in the background, orchestrating the subagents while intermediate findings stay in script variables rather than in Claude's context. Workflows handle up to 16 concurrent agents and up to 1,000 per run, are resumable, and can be saved to .claude/workflows/ as a reusable command such as /copy-audit. Including the word workflow in the prompt, or using /effort ultracode, is what triggers workflow mode.

Either way, the merge step is the same: a synthesis agent combines per-surface findings into one terminology map and one severity-ranked fix list, deduplicating issues that appear on every surface.

The style guide is the audit standard, so it has to be in a form the agent can apply. Prose guidelines like be friendly but professional do not produce consistent findings. Rewrite the guide as checkable rules: canonical terms, banned terms, voice rules with examples, error-message anatomy, reading-level targets.

The same file then does double duty as a subagent definition in .claude/agents/, which means the rules used for auditing are the same rules used when an agent later writes or reviews new copy.

---
name: copy-auditor
description: Audits product copy on an assigned surface against the content style guide. Read-only; reports findings, never edits strings.
tools: Read, Grep, Glob
---

You audit product copy against these rules. Report violations with the exact string, its location (file and key, or screen name), the rule broken, severity, and a suggested rewrite.

Terminology (canonical -> banned variants):
- transfer -> send, pay, move money (when describing account-to-account transfers)
- account -> wallet, profile (when describing the money account)
- recipient -> payee, beneficiary, contact

Voice and tone:
- Address the user as "you". Never "the user".
- Active voice. "We couldn't load your transactions", not "Transactions could not be loaded".
- No blame. Never "You entered an invalid amount"; prefer "Enter an amount between $1 and $10,000".
- No alarm words for routine states: avoid "warning", "fatal", "illegal".

Error message anatomy (all three parts required):
1. What happened, in plain language.
2. Why, if known and useful.
3. What to do next, as a specific action.

Readability:
- Target grade 7 or below for user-facing strings; flag anything above grade 9.
- Sentence case for buttons, labels, and headings. No Title Case, no ALL CAPS.

Localization risk:
- Flag concatenated strings, strings with embedded variables that change word order, idioms, and humor that will not translate.

Severity: P0 misleads or blocks the user; P1 inconsistent terminology or rule break on a primary flow; P2 tone or readability drift; P3 polish.

Agents audit what they can read, so gather the copy into the workspace first. The best source is the codebase itself: locale files, string catalogs, email templates, and component source. Add Figma exports for screens that exist only in design, and the transactional email templates from your email tool.

Note where each string lives. A finding that names the locale key or component file is fixable in minutes; a finding that names only the words sends someone hunting.

• Locale files such as en.json or strings.xml, grouped by feature where possible.
• Component source for hard-coded strings the locale files miss.
• Transactional and lifecycle email templates.
• Figma text layers for unshipped screens, exported to a text file per flow.
• Support macros and help-center titles if the audit covers them.

This prompt runs the sweep across one product area as a dynamic workflow. For a smaller audit, the same structure works as a direct fan-out of subagents without workflow mode.

Run this as a workflow.

Goal: audit all user-facing copy in the payments area against .claude/agents/copy-auditor.md.

Inputs: ./copy-audit/strings/ contains the exported locale files, email templates, and Figma text exports, grouped into:
- buttons-and-actions/
- empty-states/
- errors/
- onboarding/
- emails/

Stage 1 - Per-surface audit: launch one copy-auditor agent per folder. Each agent reads only its folder plus the style rules and returns findings as: { string, location, rule, severity, suggested_rewrite } plus a list of every term it saw used for transfers, accounts, and recipients.

Stage 2 - Merge: combine findings into:
- terminology-map.md: one row per concept with the canonical term, every variant found, and the locations of each variant.
- fix-list.md: findings ranked P0 to P3, deduplicated, with locations and suggested rewrites.
- localisation-risks.md: strings flagged for concatenation, variable order, idioms, or length.

Rules: do not edit any strings. Do not invent strings that are not in the inputs. Quote every audited string exactly. If a rule and an existing pattern conflict, report the conflict instead of choosing.

The fix list gets worked through and forgotten; the terminology map keeps paying. It records the canonical term for each concept, every variant the audit found, and where the variants live, and it becomes the reference for every future string anyone writes.

# Terminology map: payments area

| Concept | Canonical term | Variants found | Locations | Status |
|---|---|---|---|---|
| Account-to-account transfer | Transfer | Send (home screen CTA), Pay (contact detail), Move money (settings) | home.cta_send, contact.action_pay, settings.move_money_title | Fix list P1 |
| The user's money account | Account | Wallet (onboarding step 2), Profile balance (email receipt) | onboarding.step2_title, email/receipt.html | Fix list P1 |
| Person receiving money | Recipient | Payee (errors), Beneficiary (legal copy - allowed exception) | errors.payee_invalid, legal/terms section 4 | Exception logged |
| Scheduled future transfer | Scheduled transfer | Standing order (UK strings), Auto-pay (marketing email) | uk/en-GB.json, email/lifecycle-3.html | Decision needed |

Convert the style guide into the copy-auditor instruction file and get the content owner to sign off on the rules; the audit is only as legitimate as the standard it applies. Export the strings, group them by surface, and run the workflow.

Review the merged output in this order: terminology map first, because naming decisions affect many fixes at once; then P0 and P1 findings; then localization risks. Decide the contested terms with the product and legal stakeholders who own them, and record exceptions in the map rather than letting them resurface every audit.

Hand the fix list to whoever changes the strings, in passes: terminology first, errors second, tone and readability third. Then rerun the audit on the changed files to confirm the fixes landed and did not introduce new drift.

A fintech team ran the audit on their payments area before a brand refresh. Five surface agents read 1,840 strings in about 50 minutes. The merge found 96 findings, but the headline was the terminology map: the core money-movement action was called Transfer in 14 places, Send in 9, and Pay in 6, sometimes within the same flow.

Support data made the cost concrete: the most common pre-contact search was whether send and transfer were different things. The team chose Transfer as canonical, kept Pay only for bill payments, and shipped the rename across 27 strings in two days because every variant came with its locale key.

The re-audit two weeks later found 4 stragglers in email templates and zero new variants. The terminology map went into the design system docs, and the copy-auditor agent now reviews new strings in pull requests against the same rules.

A B2B platform preparing to localize into German, Japanese, and Brazilian Portuguese audited its 312 error strings first. The errors agent found that 41 percent failed the three-part anatomy, mostly missing the what-to-do-next part, and 38 strings were built by concatenating fragments at runtime, which translates badly because word order changes across languages.

Findings included strings the team had stopped seeing: a payment failure that read Error 4012: transaction declined by issuer with no next step, and a quota error written in passive voice that blamed the user in two of the three target languages once translated literally. The localization risk log went straight to the vendor, who quoted lower because the source strings were being fixed before translation rather than after.

Rewriting before translating mattered financially: fixing the 87 worst strings in English once cost a fraction of fixing them in four languages later, and the support team reported fewer tickets quoting raw error codes in the quarter after release.

A company with five products acquired over several years audited only empty states across the suite. Each product got its own agent; the merge compared them against a shared rule that an empty state must say what the screen will show, why it is empty now, and the one action to take.

Of 64 empty states, 22 were a bare No data found, 11 contradicted the product's own terminology map, and 3 pointed to actions that no longer existed after a navigation redesign. Two products had strong empty states the others could borrow, which the report identified as templates rather than treating every gap as a blank-page rewrite.

The team rewrote the 36 worst states against the shared template in one sprint, and the suite started feeling like one product in exactly the screens new users hit first. The before-and-after copy table from the audit became the example set in the style guide.

A weak audit reports impressions; a strong audit quotes the string, names where it lives, names the rule, and proposes a rewrite the owner can accept or decline. The difference decides whether the fix list gets executed or politely ignored.

The audit measures consistency against a standard; it cannot prove the standard is right. Whether Transfer or Send is the better word for your users is a naming decision informed by research and brand, made by humans, and only then enforced by the audit. Reading-level scores are rough instruments, useful for flagging outliers, not a substitute for testing comprehension with real users.

Agents also cannot judge legal and regulatory copy, accessibility of the surrounding design, or whether a friendly rewrite loses a nuance compliance needs. Route those findings to the owners who can decide, and record their decisions as exceptions so the next audit does not relitigate them.

Finally, the audit only covers the strings you exported. Hard-coded copy, third-party widgets, and copy living only in screenshots will be missed unless someone goes and finds it.

• Cannot choose the right term; it can only show how many terms are in use and where.
• Cannot certify legal, regulatory, or accessibility compliance.
• Cannot measure whether users actually understand the copy; that needs testing.
• Cannot see strings that were never exported into the audit inputs.

Keep the copy-auditor instruction file, the prompt, and the artifact templates in the repo, and save the prompt to .claude/workflows/ as /copy-audit. Rerun it per product area each quarter, or wire the auditor agent into pull-request review so drift is caught one string at a time instead of 1,800 strings at a time.

1. Convert the content style guide into a checkable copy-auditor instruction file.
2. Export strings from locale files, emails, and Figma; group them by surface.
3. Run one audit agent per surface (as a workflow for large areas).
4. Merge findings into a terminology map, a severity-ranked fix list, and a localization risk log.
5. Decide contested terms with the owners and log exceptions in the map.
6. Fix in passes: terminology, then errors, then tone and readability.
7. Re-audit the changed surfaces to confirm the fixes and catch new drift.
8. Update the style guide and keep the auditor agent reviewing new strings.