batch-rewrite-pattern

Batch Rewrite Pattern

When the same edit needs to land in N files, the worst shape is N sequential manual passes. Each pass collects its own errors; the hook system retriggers; context fills with repetitive diffs. This skill captures the better shape.

Triggers

Activate when any of these apply:

• Renaming a symbol across the tree
• Migrating a function signature (add/remove/reorder args)
• Swapping an import path across modules
• Converting between two patterns (callbacks ↔ promises, v1 ↔ v2 API)
• Any edit where you can describe the transformation as "in every file

matching pattern X, replace Y with Z"

Typical count trigger: ≥ 4 files warrant the batch shape.

Workflow

1. Characterize the transformation in one paragraph:
2. What's the before pattern? (regex or literal)
3. What's the after pattern?
4. Are there variants? (single pattern vs family of patterns)
5. Any files that should be exempt?

1. Enumerate candidates with Grep/Glob:

`` Grep pattern=BEFORE output=files_with_matches ``

1. Dry-run the rewrite against 1-2 candidates first. Verify:
2. The transformation is correct
3. Surrounding context isn't disturbed
4. No collateral damage

1. Apply in a batch — prefer a single Bash sed/perl invocation or a

small rewrite script over N sequential Edit calls: ``bash for f in $(grep -l 'BEFORE' src/**/*.ts); do sed -i -e 's/BEFORE/AFTER/g' "$f" done `` Or write a one-shot node script that reads each file, applies the transformation, writes back.

1. Verify with the test suite if one exists, or with a grep that the

after-pattern is uniformly present and the before-pattern is gone.

1. Single commit covering the whole cascade, scope line listing files.

Anti-patterns to avoid

• Sequential manual Edit calls when the transformation is deterministic.

Each Edit triggers hook re-reads and bloats context.

• Partial cascades — leaving some files on the old pattern because you got

interrupted halfway. Either all or none; use git stash to revert if the cascade was wrong.

• Branching transformations without a plan — when "most files" follow one

pattern but a few need a variant, enumerate the variants first and handle each as its own batch.

Example — Config Adapter Cascade (v1.49 release-history work)

Situation: 11 scripts in tools/release-history/ each had a direct pg.Client instantiation and hardcoded paths. Needed to convert all 11 to use loadConfig() + openDb(cfg).

Right shape:

1. Wrote the adapter (db.mjs) once
2. Characterized the transform: replace new pg.Client({...}) block with

await openDb(cfg); replace hardcoded paths with cfg.*_abs

1. Applied to each file in one Bash loop or parallel sed invocation
2. One commit

Wrong shape (what actually happened): 11 sequential Read-plus-Edit cycles, 35+ read-before-edit hook fires, recursive pattern-matching at each step.

The lesson: when you feel yourself about to do the same edit for the fourth time, stop and batch the rest.

Companion Tools

• Grep with output_mode: files_with_matches to enumerate candidates
• Bash with sed -i or a small rewrite script for the cascade
• Grep again to verify the before-pattern is gone and after-pattern is

uniformly present

Related

• file-operation-patterns — safe bulk file operations
• decision-framework-invoker — use when the batch is irreversible