Bulk Sweep Classify

Bulk Sweep — Classify Every Match First

When you modernize a syntax across many files with a regex / sed / perl pass — a command rename (/ns:cmd → /ns-cmd), a tool/binary rename, a path or import-style migration, an API-version bump in prose — the matched set is heterogeneous even though every hit looks textually identical. One pattern catches genuine stale targets and several look-alikes that must NOT be transformed. Blindly rewriting all matches corrupts the look-alikes silently: the sweep reports success, and the damage surfaces far downstream (a broken designed filename, a rewritten immutable record).

The discipline: enumerate the matches and bucket every one into a category before editing. The regex sees text; the transform needs semantics.

When to Use This Skill

The Four Categories

Read the surrounding line of each match and bucket it. Each category needs different handling.

Category 3 is the sharpest trap. The delimiter you're replacing (:, /, ., -) often also appears in filenames, config keys, or URLs that the matched token participates in. Hyphenating /sync:daily → /sync-daily also rewrites every sync:daily-state.json path in the same doc — silently breaking a design.

Category 4 follows the standard supersede-don't-rewrite convention: set Status: Superseded plus a top-note, leave the body as a historical record.

Execution

Step 0: Route by sweep target — code vs. prose/docs

Before enumerating, decide what you are sweeping. This picks the transform engine and shrinks the classify workload:

• Sweep target is code — an API rename, call-site migration, or import-path change in source files. Do the transform structurally with ast-grep -p '<old>' -r '<new>' --lang <l>, delegating the transform mechanics to code-quality-plugin:ast-grep-search. An ast-grep pattern matches AST nodes, so it inherently won't match inside strings, comments, or URLs — the whole category-2 false-positive bucket shrinks to near-zero. The classify pass then focuses on categories 3 (designed filenames/paths) and 4 (immutable records) only, and Steps 1–2's false-positive tightening is largely unnecessary. Proceed to Step 3 with the ast-grep result in hand.

• Sweep target is prose/docs/mixed — command renames in markdown, tool names in docs trees, an API-version bump in prose. Regex sees text, not semantics, so the four-category discipline below is unchanged and remains this skill's core case. Run the full Step 1 → Step 5 pipeline.

The decision hinges on whether a structural matcher can see your target: code has an AST, prose does not. When in doubt (a rename that spans both source and its surrounding docs), split it — ast-grep the source, then run the four-category pass over the docs.

Run this classify-then-transform sweep:

Step 1: Enumerate every match, deduped, before touching anything

git grep -nhoE '/[a-z][a-z0-9-]*:[a-z][a-z0-9-]*' -- <scope> | sort -u

Adjust the pattern to your migration. The point is a complete, deduped inventory in hand before any edit.

Derive the term set from what the mechanism claims, not just what it is named

The enumeration is only as good as the terms you feed it. Removing a mechanism means removing its assertions as well as its identifiers, and those two families share no tokens — so a sweep built only from identifiers reports clean while the claim survives.

After listing the identifier terms, ask: what did this mechanism promise, and in whose words? Add those phrasings to the term set. For a removal, terms usually come in two families:

The claim family is where user-facing damage concentrates. An identifier left behind is dead code, but a claim left behind is documentation that is now false.

Concrete case (ForumViriumHelsinki/podio-mcp, PRs #160 / #163 — issue #2479): a build-time credential injector was removed. The sweep terms were the identifiers — BUILD_DEFAULTS, inject-build-defaults, postbuild — which correctly found the script, the npm hook, the constants module and the workflow passthrough, and the PR shipped. It missed this, in a file the sweep had already edited:

src/index.ts:134
 * - PODIO_CLIENT_ID: Your Podio app's client ID (baked into published package)

The comment asserts exactly what the mechanism was supposed to do and contains none of the three identifiers. It survived, typedoc renders it into the API reference, and so the claim outlived the thing that made it true — caught only incidentally, one PR later.

Step 2: Tighten the pattern to drop false positives at the source

Drive the false-positive exclusion into the pattern wherever you can, so the sweep mechanically cannot touch category-2 hits. Example: requiring a letter after the colon (:[a-z]) excludes :6379 ports and redis:// URLs. This removes the whole class from manual consideration.

Step 3: Bucket every remaining hit into categories 1–4

Read the surrounding line of each match. Reserve manual judgment for categories 3 and 4 — they look like real targets and can only be told apart by reading intent. Record which files/lines fall into categories 2–4 (the intentionally-preserved set).

Step 4: Scope the transform to category-1 files ONLY

perl -i -pe 's{/([a-z][a-z0-9-]*):([a-z][a-z0-9-]*)}{/$1-$2}g' <category-1 files>

Pass only the category-1 files. Hand-handle categories 3 and 4: category 3 is left untouched; category 4 gets a supersede/status note with its body left intact.

Step 5: Verify against the preserved set, not literal zero

Re-run the enumeration from Step 1. The correct success test is NOT "zero matches remain":

Zero matches remain outside the intentionally-preserved set.

Categories 3 and 4 are supposed to keep matching. Confirm the grep returns only the category 2–4 lines you identified in Step 3.

For the code route (Step 0), the preserved set is whatever ast-grep's structural match legitimately leaves behind — the old form still cited inside strings, comments, or URLs that the AST matcher never touched. Verify it the same way: re-run the enumeration and confirm the only remaining matches are those non-code occurrences (plus any categories 3/4), not genuine call sites.

The Verification Trap

The naive success test — "re-run the grep; it should return nothing" — is wrong, because categories 3 and 4 legitimately still match. A verification that demands literal zero will either fail spuriously or — worse — pressure you into corrupting a category-3 design or rewriting a category-4 record just to force the count to zero. Enumerate the preserved buckets up front, then verify the grep returns only those.

The adjacent trap sits one level up, in the scope the verification runs over: every exclusion in a verification scope is a claim about the world, and needs the same treatment as a negative result. "Generated, so it doesn't count" assumes the generator runs — check that it does. Cheap test: for each excluded path, state why in one line, then verify that line. In the same sweep (#2479) the final pass excluded docs/api/ — committed typedoc output — reasoning that CI regenerates and publishes it. Both halves were false: GitHub Pages was never enabled on the repo (/repos/.../pages → 404) and the deploy workflow had failed every run for ten days, so the excluded directory was the only rendered copy and still carried the stale claim. The report said "no matches remain," which was true of what it searched and false of the repo.

Agentic Optimizations

Related

• verify-upstream-before-patching / read-issue-thread-before-contributing — establish authoritative intent before acting, don't trust a surface signal
• git-hazards — an automated pass reporting success is not proof the result is correct; verify the content, not the exit code
• code-quality-plugin:ast-grep-search — structural search/replace when the pattern depends on AST shape rather than text
• agent-patterns-plugin:parallel-agent-dispatch — the dispatch contract a fanned-out sweep rides on; the rename map is the payload you brief into it
• agent-patterns-plugin:adversarial-review — the audit pass; brief it with the artifact's purpose, not only the transform contract

For parallelizing a sweep across agents (the pre-dispatch rename map and do-NOT-rename list) and for briefing adversarial auditors, see REFERENCE.md.