Review Copy

Review copy

Score a piece of user-facing copy against VOICE.md, fix what fails, then verify the fixes actually landed. The loop exists because a single pass reliably misses things and reliably claims fixes it didn't make.

Target: $ARGUMENTS — a file, a directory of Swift views, a docs page, a PR body, or pasted text.

Before anything

Read VOICE.md at the repo root. It is the standard; this skill is only the loop that applies it. If the two ever disagree, VOICE.md wins.

Never calibrate against neighbouring strings in this repo. Most of them were written with AI assistance, so "it matches the file around it" is evidence of nothing. For UI copy, the reference is the macOS System Settings pane that does the same job — read Apple's wording, then write termio's.

The loop

score → fix the failures → re-score to verify → repeat until it holds

State lives in a tracker file under the scratchpad so a second pass doesn't re-discover the same issues or trust an unverified claim:

Path: <scratchpad>/copy-review-<name>.md

# Copy review: [target]

| ID  | String / line        | Issue            | Status         | Round |
| --- | -------------------- | ---------------- | -------------- | ----- |
| 1   | Settings.swift:214   | subject is "you" | pending        | 1     |
| 2   | page.tsx:80          | "seamlessly"     | verified-fixed | 1     |
| 3   | FileNode.swift:31    | mechanism copy   | wont-fix       | 2     |

## Rounds
### Round 1 — Voice 6/10, Accuracy 8/10 (14/20)

Status values: pending · fixed (claimed, unverified) · verified-fixed · not-fixed · wont-fix (intentional, out of scope, or a false positive).

Step 0 — The mechanical pass

Cheap, exact, and it clears the noise before anyone reads for tone. Run these over the target first and fix every hit; none of them need judgment.

# straight apostrophes in user-facing strings — should be curly (’)
grep -rnE "\"[^\"]*[a-zA-Z]'(t|s|re|ll|ve|m|d)\b[^\"]*\"" <target> | grep -v 'Log\.\|logger\|// '

# "could not" where a contraction belongs (skip log strings and matched tool output)
grep -rn '"[^"]*[Cc]ould not' <target>

# Title Case on what is a sentence, not a feature name
grep -rnE '"(Can|Couldn|Cannot|Unable)[^"]*[a-z] [A-Z][a-z]+' <target>

# emoji in copy
grep -rnP '"[^"]{3,}"' <target> | grep -P "[\x{1F300}-\x{1FAFF}\x{2600}-\x{27BF}]"

# trailing gerunds — every hit is a candidate, neutral ones included
grep -rnE '"[^"]*, [a-z]+ing\b[^"]*"' <target>

Rewriting apostrophes across a tree is safe only inside string literals. Check first that no match sits in a shell command being built for execution, then operate on quoted substrings rather than whole lines, so comments and identifiers are left alone.

Step 1 — Score

Two dimensions, 0–10 each. Score them separately; they fail for different reasons and get fixed by different means.

VOICE — does it read like a person wrote it?

Check in this order; the first two catch the most and are the easiest to miss because the result reads fine.

1. Trailing gerunds — grep the target for , [a-z]+ing\b. Every hit is a candidate: "allowing you to", "making it easy to", "ensuring". Neutral ones count.
2. Regression to the mean — has a specific fact been smoothed into a generic? "helps you review your agents' work" where the truth was "shows changes, a file tree, and the transcript".
3. One idea per sentence, whatever its length
4. Honest: says what the control won't do or what it costs
5. Empty states and errors name the next action
6. Rhythm: do the sentences vary in length, or all run the same?
7. Fixed vocabulary (Group with / Ungroup / Close Session, lowercase termio)
8. Sentence case for sentences, Title Case for feature names; curly apostrophes; Couldn't over Could not
9. Remaining AI tells (hollow importance, rule of three, promotional adjectives, negation parallelism, emoji), no AI attribution
10. Nothing implying termio is paid

ACCURACY — is it true?

This is the dimension that matters most for termio and the one a style pass skips. A subtext that describes behavior is a claim about the code.

• Read the code behind the string. Does the control do what the string says?
• Does a named path, flag, or command still exist and still spell that way?
• Is a capability described as shipped actually shipped, and on the release channel rather than only on dev?
• Do landing-site claims match Sources/? (Recurring failure — see the termio-capabilities history: copy outran the code twice.)

For a wide sweep (a whole settings tab, the landing site), score VOICE and ACCURACY in separate passes rather than one — a single pass reading for both consistently under-reports accuracy.

Write every failure into the tracker with its file and line. A finding without a location can't be verified later.