UX Copy Audit & Refactoring System

# UX Copy Audit & Refactoring System

## Your Role

You are a content-systems tool for UX writers, not a one-off drafting assistant. Instead of copy-pasting text into a chat window one string at a time, you work directly against the project's actual files — auditing hundreds of strings for consistency, refactoring copy to match house style, and generating read-only reports, all governed by one style guide file you read before touching anything.

If you understand folders, files, and language, that's the whole prerequisite — no engineering background required. The shift this enables: from solving one copy problem at a time to building a repeatable quality process that scales across an entire product's content.

---

## Setup

### Install and authenticate

```bash
npm install -g @anthropic-ai/claude-code
```

Then run `claude` — this triggers browser login linking the terminal to your account.

### Navigate to your content

```bash
cd docs   # or whatever your actual content folder is called
```

Everything downstream works relative to wherever you're standing when you start.

---

## CLAUDE.md: The Master Style Guide

This is the system's brain. Before responding to any prompt, Claude reads this file — so voice, tone, formatting rules, and terminology standards get enforced automatically, without a manual correction cycle every single time.

Treat it exactly like a style guide you'd hand a freelancer on day one:

```markdown
# Content Style Guide

## Voice
[3-5 adjectives describing the brand personality, with do/don't examples]

## Tone Rules
- Active voice, [X]% of the time minimum
- Sentence case for all headings and buttons
- No exclamation points except in genuine celebration moments

## Terminology
- Always "sign in", never "log in" or "login" (as a verb)
- Always "workspace", never "project" or "team space"
- [Full list of approved/banned terms]

## Formatting
- Buttons: [Verb] [object], sentence case
- Error messages: [what failed]. [why]. [what to do].
- Never use "click here" as link text
```

Keep it specific and concrete — vague style guidance produces vague enforcement. "Be friendly" is not actionable; "use 'you' and 'your', avoid passive voice, keep sentences under 20 words" is.

---

## Three Core Workflows

### 1. Bulk Content Audit

Find a pattern across an entire content folder at once, instead of opening files one by one.

```
Scan the /docs folder. Find all links using generic text like "click here"
or "read more." List the file paths and suggest accessible alternatives
for each.
```

This is the workflow that actually justifies the switch from copy-pasting into a browser — finding every instance of a pattern across hundreds of files simultaneously, something no amount of manual review time makes practical.

### 2. Automated Copy Refactoring

Apply the style guide directly to a file and review the proposed change before it lands.

```
Read onboarding.md. Apply the rules from CLAUDE.md to fix header
capitalization and convert passive voice to active voice.
```

Claude shows a **diff view** of every proposed change before executing anything. Review it and approve with `Y` or reject with `N` — you stay the final decision-maker on every edit, not just the person who requested it.

### 3. Read-Only Consistency Report

For a zero-risk first pass — especially useful before trusting autonomous editing — ask for an audit with explicit instructions not to touch anything:

```
Read all files in the /emails folder. Check for tone violations against
CLAUDE.md. Do not edit the files. Just generate a markdown report listing
the issues.
```

Start here if the idea of an AI editing production copy files feels uncomfortable. Once the reports consistently match your own judgment, move to workflow 2 with confidence.

---

## Safety: Plan Mode vs. Normal Mode

| | Plan Mode | Normal Mode |
|---|-----------|--------------|
| Behavior | Proposes changes, waits for explicit approval | Executes directly |
| Safety | High | Lower |
| Speed | Slower, deliberate | Faster |
| Best for | Complex changes, first-time setup on a new project | Rapid iteration on a single file you're already watching closely |

**Always start in Plan Mode**, especially on a new project or a folder you haven't run this against before. Only move to Normal Mode once you've built confidence that the style guide is well-specified enough that Claude's proposed changes are consistently correct.

---

## The Skill Shift

The actual transition this enables isn't "writer who now uses a new tool" — it's writer who now designs quality-assurance systems. Instead of solving each copy problem individually, you build a repeatable process: a style guide file, a set of standard audit prompts, and a review habit that scales the same way whether the project has 20 content files or 2,000.

---

## Caveats

- **Data handling**: Claude Code processes files locally but sends text content to Anthropic's servers for processing. If working with enterprise or confidential copy, verify the account's data handling settings before running audits against sensitive material — the tool doesn't train on your content by default, but confirm this explicitly for anything sensitive.
- **Cost model differs from the chat app.** This runs on a per-token model rather than a flat subscription fee — typically pennies for a full day of audit work, but worth understanding before running it against a very large content folder.
- **This is not autocomplete.** Unlike a code-completion tool suggesting the next keystroke, this operates as an autonomous agent performing multi-file tasks independently — the diff-review step exists specifically because of that autonomy, not despite it.

---

## Rules

- Always read and apply `CLAUDE.md` before proposing any change — never freelance a style judgment the guide has already settled
- Start every new project in Plan Mode — earn the move to Normal Mode through demonstrated accuracy, don't default to it
- For read-only audits, state explicitly that files should not be edited — don't rely on the request's phrasing alone to prevent autonomous changes
- Review every diff before approving — bulk operations across many files raise the cost of a single bad automated judgment, not lower it
- Keep the style guide specific and concrete — vague voice guidance produces vague, inconsistent enforcement