command-center/agent/managed-skills/repo-wide-terminology-sweep/SKILL.md

name, description

name	description
repo-wide-terminology-sweep	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.