---
name: repo-wide-terminology-sweep
description: "Rewrite or retire a phrase/term across every comment in a repo (e.g. jargon ban, de-law comments) without breaking tests or leaving ragged prose seams"
---

Use when asked to eliminate/replace a word or phrase in comments across a whole repo (jargon bans, style cutovers, retiring event-narrative lore).

## Procedure

1. **Census with word boundaries.** `git ls-files -z | xargs -0 grep -inwE "term(s)?"` — plain substring grep drowns the list in false positives (e.g. `law` matches inside `alloy`-adjacent noise, `download`, `flaw`). Exclude docs explicitly if scope is comments only (`grep -v "^docs/\|^AGENTS.md:"`).
2. **Dump all hits with line numbers** in one pass, then batch-read each site's surrounding block (`read file:start-end`). Comments span multiple lines; a single hit line rarely carries the full claim.
3. **Check tests pin comment text BEFORE rewriting.** Suites sometimes grep exact comment strings; those seams need rewiring (test the contract, not the prose), found by running affected bats/pytest files after each file's edit, not at the end.
4. **Rewrite around the mechanism, not the incident.** Replace dated narratives and jargon with: the constraint, the mechanism enforcing it, the consequence of violating it. Keep project-specific parameters (paths, flags, sizes) — they are the subject; generalize the *reasoning* so it transfers.
5. **Edit multi-line blocks as whole blocks.** When replacing the middle line of a wrapped sentence, include ALL continuation lines in the replacement body. Partial bodies leave seams: sentences ending mid-clause, duplicated lines, orphaned fragments.
6. **Seam hunt after editing.** Review `git diff -U0` added lines for the block mid-sentence heuristic (`grep -E "(the|a|of|and|at|per|by|is|in|to|for)$"`), then re-read every site where the diff boundary fell inside a paragraph; verify the full sentence reads coherently.
7. **Verify behavior-identical.** `bash -n` every touched shell file, `py_compile` touched Python, parse touched YAML, run the FULL suite — comment sweeps must exit 0 with the same test count as before. A green suite does not prove prose is intact; step 6 does.
8. **One atomic commit**; state the rewrite law in the message with a few old→new example pairs.

## Pitfalls

- Jargon often escapes into identifiers and log strings (`scale_law` variable, refusal messages) — grep word-boundary matches in code, rename locals/messages only if no test pins the string.
- Line anchors drift between files edited in the same batch; on a stale-anchor error the tool shows real content — re-target, don't re-read blindly.
- `.AGENTTRASH/` and retired `old/` trees: exclude from scope, they are archives.