# Copy Audit > Review product copy and UI microcopy against cited writing standards — plain language, inclusive language, UX microcopy, and voice and grammar — then apply the edits you approve, changing only the text and never the surrounding code or markup. It reads markdown prose, headings, and alt text, JSON, YAML, and TOML values, and UI strings in HTML, Astro, Svelte, Vue, and JSX/TSX across a repo or a diff. With --mode=comments it also reviews code comments and test names (it/describe/test) for low-value or misleading comments and vague names — this replaces the earlier comment-audit skill. Parallel subagents judge each item in full-file context, and nothing is written until you approve. Use for /copy-audit, a copy, content, or microcopy review, a readability, plain-language, or inclusive-language pass, a docs or markdown polish, or a comment and test-name audit — "comment cleanup", "AI comment slop", "test name audit", "Rule 9 sweep". - Skill: `kaelys-js/copy-audit` (Agent Skill, multi-file: 77 files) - Install (CLI): `npx skillmds@latest add kaelys-js/copy-audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/kaelys-js/copy-audit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - License: MIT. See LICENSE. - Author: kaelys-js (https://skillmd.com/u/kaelys-js) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/kaelys-js/copy-audit --- # copy-audit UX copy, marketing prose, docs, and microcopy drift from best practice on long-running branches faster than any one reviewer can keep up with. This skill sweeps a repo (or a diff range) end to end: it parses every **copy unit** — markdown prose and headings, UI microcopy, JSON/YAML copy-key values, string phrases in copy modules — lets AI subagents judge each one against the four content-standard pillars in [reference/standards.md](reference/standards.md), then applies the verdicts to disk with a **char-offset exact-match splice** that only ever rewrites the human-readable text (the surrounding quotes, tags, markdown markers, and JSON structure are byte-identical) and a **per-file SHA guard** that refuses to touch a file that changed since extract. Every phase is idempotent and inspectable — the sqlite DB is the source of truth for verdicts, so an orchestrator can review the tables before committing to disk, defer files, or resume mid-sweep. Copy is subjective and high-stakes, so **nothing is auto-deleted and nothing writes without your go-ahead**: the flow stops after review for approval. ## When to invoke - User asks for a copy / content / writing / microcopy review of a repo, PR, branch, or folder ("review the copy", "UX writing pass", "tighten the wording"). - User wants a plain-language, readability, inclusive-language, or brand-voice sweep of markdown docs, a marketing site, or UI strings. - User says "do the copy sweep" (recurring cadence on a long branch) — see **Incremental / delta sweeps**. ## What it is not - Not a translator, not an SEO keyword tool, not a grammar-only linter. It reviews copy against the four pillars and preserves meaning, product names, numbers, and URLs. - Not a code reviewer. Code strings, identifiers, and config values are filtered out at extract; any that slip through get a `keep` verdict. ## Execution model: script phases in subagents, review and approval here The Workflow-tool review fan-outs (`copy-review.js`, `copy-holistic.js`), the review-before-apply approval gate, and any commit the operator asks for stay in the main conversation — the Workflow tool is invoked from here, and a subagent cannot ask for approval. The script phases run in Agent-tool subagents so a whole-repo extract, the verdict tables, and the verify report never share the operator's context. Every subagent: `subagent_type: general-purpose`, `model: claude-opus-4-7`, a self-contained prompt carrying absolute paths for the skill's `extract.mjs`, the repo, the DB, and the bundle dir plus the mode, range, and skips the operator gave, and "Do not delegate". 1. **Extract subagent** — `description: copy-audit extract: `. Runs `extract` then `bundle-emit` (and `holistic-emit` when a holistic pass was asked for). Returns only unit counts per file and syntax, the bundle count, and the manifest path. 2. **Review (inline)** — call the Workflow tool with `copy-review.js` on those bundles and collect `verdicts.json` as described under Phases. 3. **Verdict subagent** — `description: copy-audit verdicts: `. Runs `apply-verdicts`, then reads the DB and returns a compact approval summary: per file, every `rewrite` as before → after and every `flag` with its note, plus the keep count. It writes the DB only; it never runs `apply`. 4. **Approval gate (inline)** — show the summary and STOP. Nothing writes to the repo until the operator approves, file by file if they want. 5. **Apply subagent** — `description: copy-audit apply: `. Its prompt carries the approved file list verbatim. Runs `apply` (deferring any file not approved by setting its rows to `keep` first), then `verify` with the repo's `--post-verify-cmd` when one exists, and returns the verify report and per-file stat. ## Modes (`--mode` on every phase) - **`copy`** (default) — product copy & UI microcopy, judged against the four content pillars. - **`comments`** — code-comment slop and test-runner names (`it`/`describe`/`test` first args), judged against comment-quality rules (WHY-not-WHAT, delete restate/scar/dead comments) and Rule 9 (a test name must encode intent, not shape). This is the subsumed **comment-audit** behaviour, now AST-based: comment nodes come from every tree-sitter grammar (40+ languages) and babel (JS/TS), so it is far more robust than the old regex parser. Test files are audited in this mode (skipped in `copy`). Verdicts add `delete`; a `delete` on a test name is refused (it would break the runner call). - **`all`** — both. `node scripts/extract.mjs --phase=extract --mode=comments --repo --full --head HEAD --db ` ## Anatomy ```text copy-audit/ SKILL.md -- this file reference/ standards.md -- the four pillars, as cited checklists + evidence (Aug 2026) usage.md -- worked end-to-end run + the review workflow shape reference/ extraction-research.md -- cited best-practice for the web-stack parsers (Aug 2026) extraction-multilang-research.md -- cited best-practice for tree-sitter multi-language (Aug 2026) scripts/ extract.mjs -- the engine: phases + JSON/text + wiring ast-extract.mjs -- AST extraction (babel / @astrojs/compiler / remark / yaml) ts-extract.mjs -- tree-sitter extraction for the broad language set grammars/ -- vendored modern-ABI tree-sitter grammar .wasm files schema.sql -- sqlite table definition package.json -- vendored deps pin node_modules/ -- vendored (better-sqlite3, @babel/parser, @astrojs/compiler, -- web-tree-sitter, tree-sitter-wasms, yaml, mdast) — no install step selftest.mjs -- regression battery + spec/trigger validation workflows/ copy-review.js -- per-unit reviewer fan-out (keep/rewrite/flag) copy-holistic.js -- whole-page holistic reviewer (cross-cutting findings) ``` Extraction is **AST-based** (real parsers, not regex): `@babel/parser` for JS/TS/JSX/TSX, `@astrojs/compiler` for Astro, `remark`/mdast for markdown, the `yaml` CST for YAML, an offset-tracking scanner for JSON, and **tree-sitter** (web-tree-sitter WASM + prebuilt grammars) for the broad language set. One classifier (`isCopyPhrase`) decides copy vs code. Invoke every phase as `node scripts/extract.mjs --phase= ...`. All phases share one sqlite DB (`--db `) and act on rows in specific verdict states, so re-runs are safe and the DB alone tells you where a sweep is in its lifecycle. ## Phases ### 1. `extract` — parse copy units ```text # Git mode — a diff range or the whole working tree: node scripts/extract.mjs --phase=extract \ --repo # absolute path to a git worktree --base # baseline ref (exclusive); omit when --full is set --head # head ref (inclusive) --db # sqlite DB path (created if missing) [--full] # whole-repo sweep: base = empty tree, so EVERY copy unit is # audited, not just those added in a range (two-dot diff) [--files-list ] # optional newline-separated file allowlist [--skip-path ] # optional extra path-substring skips (comma-sep / repeatable) # Direct mode — audit one pasted string / standalone file, no git needed: node scripts/extract.mjs --phase=extract --db --input [--as <.ext>] printf '%s' "$PASTED" | node scripts/extract.mjs --phase=extract --db --stdin --as <.ext> ``` Walks `git diff --name-only ${base}...${head}` (or the whole tree with `--full`), filters by extension + skip rules, and for each survivor parses every **copy unit** into the `units` table, recording exact `char_start`/`char_end` offsets of the editable payload. Wipes rows for this `repo` first so re-runs are clean. **Working-tree coupling.** `apply` and `verify` always operate on the on-disk (working tree) file, so when `--head` is the current `HEAD`, extract reads file **content** from the working tree too — a file with uncommitted edits is audited as it actually is on disk, and its `file_sha`/`block_text` match what `apply` will splice into. (A historical `--head` — a past commit — still reads content via `git show`; that is a review-only audit, since apply can only write the working tree.) Without this coupling, a dirty tree would be audited from its committed content and every `apply` would trip the SHA guard. **Direct input (`--input` / `--stdin`).** To audit pasted text or a single file that is not in a git repo, pass `--input ` (or pipe the text with `--stdin`), and `--as <.ext>` to declare the format (`.md`, `.json`, `.html`, …) so the right extractor runs. The rest of the pipeline is unchanged — `apply` still splices by SHA-guarded char offset, and `verify` proves the copy-only invariant by reconstructing the file from its pre-image + the applied rewrites (an exact match means nothing outside a recorded span moved). With `--stdin`, the text is written to a real file (use `--input` to choose where) so apply/verify have something on disk. **File types → unit kinds:** | Extensions | Copy units captured | `syntax` | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `.md` / `.mdx` / `.markdown` / `.mdc` | headings, prose paragraphs, list items, blockquotes, standalone-image alt text; YAML frontmatter values | `md-heading`, `md-prose`, `md-listitem`, `md-blockquote`, `md-alt`, `frontmatter` | | `.json` / `.jsonc` / `.json5` / `.webmanifest` | string values (and arrays of strings) under copy-carrier keys, walked with an offset-tracking JSON scanner (tolerates `//` + `/* */` for jsonc) | `json-copy` | | `.yml` / `.yaml` | scalar values under copy-carrier keys | `yaml-copy` | | `.html` / `.htm` / `.vue` / `.svelte` / `.astro` | visible text nodes + `alt` / `title` / `placeholder` / `label` / `aria-label` / `aria-description` attributes (with `