tibsfox/gsd-skill-creator/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:

• What's the before pattern? (regex or literal)
• What's the after pattern?
• Are there variants? (single pattern vs family of patterns)
• 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:

• The transformation is correct
• Surrounding context isn't disturbed
• 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