Secondary Text Audit

Secondary-Text Audit

Extract every piece of subordinate copy in a surface and put each one on trial. The ruleset's premise is that secondary text defaults to absent: it exists only to carry information the user needs before acting that the label, the control's shape, and the surrounding context do not already give them. Most shipped secondary text describes what something is, which the label already did. That text goes.

The output is a verdict table, not prose commentary. Every row resolves to keep, rewrite, or delete, and every rewrite carries its replacement string.

Design philosophy (read this — it shapes every judgment call)

1. Delete is the expected majority outcome. This is the inversion that makes the skill useful. An audit that keeps most of what it finds has not applied the ruleset; it has admired the copy. If your table is mostly keep, re-run the fact test on every keep row and mean it.

2. Uncertainty resolves to delete, with one exception. When a string sits between delete and rewrite, choose delete — the primary label almost always suffices. This is the opposite of the precision-over-recall bias in ux-semantics-audit, and deliberately so: a wrong keep is permanent noise on the screen.

   The exception is a string carrying a cost, a scope, or a cause. Deleting one of those does not cost a line of copy, it costs the reader the fact that made the screen actionable. When the string tells the user what an action breaks, where a setting stops applying, or why a surface is in a state they did not choose, uncertainty resolves to rewrite. Trim it to the fact and keep it.

3. Judge the rendered pair, never the key name. A verdict needs the label the user actually sees next to the text. A key called *.description may render as a card subtitle, a tooltip body, a dialog description, or nothing at all.

4. Fact before verdict. Name which kind of fact the text carries before deciding anything. A string carrying none is delete — that is the rule, not a shortcut.

5. A rewrite must be a real string. "Tighten this" is not a replacement. Write the sentence that ships, in the register docs/ui/VOICE.md fixes. If you cannot write one that passes the rules, the verdict was delete.

6. A shorter string is not automatically a better one. Trimming is the means, not the goal. A replacement that reads as a system log has failed even when every word left is load-bearing — check it against VOICE.md before it ships.

Workflow

Step 1 — Scope the audit

The unit of analysis is the surface: a page, tab, dialog, drawer, or self-contained section. Secondary text is judged against what renders beside it, so the scope must be something the user sees at once.

• Whole package → audit surface by surface; do not emit one 120-row table.
• A named page ("the settings page", "the app detail page") → that page and the dialogs it opens.
• New copy the user just wrote → that string plus its label and siblings.

Step 2 — Extract the candidates

node .claude/skills/secondary-text-audit/scripts/extract-secondary-text.mjs --scope settings

The script collects both carriers Rome uses — i18n locale keys under packages/web/src/i18n/locales/<locale>/ and literal strings in *Description components and description= / subtitle= / hint= / helperText= props — pairs each with its label, resolves it back to the component that renders it, and prescreens it. --scope <substr> filters by key or location; --json emits the rows for programmatic use; --root points at another package.

Its flags are advisory triage, not verdicts:

• forbidden:* and generic-verb are near-certain delete, but confirm the match is real before writing it down.
• no-signal fires on most rows. It means "re-examine", nothing more — real cost text often has no number.
• sr-only rows are out of scope entirely. Never delete them.
• UNRENDERED means no call site was found. Confirm with a grep for the bare key before calling copy dead, then verdict it delete.
• dynamic-key and key-ref are the weakest resolutions and can over-match: a computed key like connections.headings.${role} matches every sibling under that prefix, including ones the union type never produces. Open the cited line and check the key can really reach this row before trusting it — a row that only resolves this way is a delete candidate hiding behind a wildcard.
• label-inferred means the label shown is a guess from the key path. Read the component before judging that row.

Step 3 — Read the ruleset and the voice

Read docs/ui/VOICE.md first — it fixes the register, the person, and what a description must carry, and every rewrite row is written in it. Then read docs/ui/secondary-text.md in full. It carries the scope, the five kinds of fact, the four-question test, and the repo rules. Do not audit from memory of the kind names.

Step 4 — Establish the rendered context

For each surface, read the component and write down, before judging anything:

• the label rendered above/beside each string, verbatim;
• the siblings rendered on the same screen (this decides every difference verdict);
• whether the string is conditional — empty-state only, error-only, first-run only (this decides first-step text and pulls error copy out of scope);
• what the control's shape already says — a toggle, a file input, and a destructive-variant button each carry information the copy need not repeat.

This step is what separates a verdict from a guess. Skipping it produces plausible-sounding tables that are wrong about half the rows.