batch-operations

name	batch-operations
description	Apply operations across multiple files simultaneously. Pattern-based bulk modifications, search-and-replace across codebases, consistent changes to many files at once.
when_to_use	When the user needs to change multiple files with the same pattern, rename across a codebase, add imports to many files, update versions, or apply consistent modifications. NOT for single-file edits.
allowed-tools	Read, Write, Edit, Grep, Glob, Bash
effort	medium

Batch Operations — Multi-File Changes

Apply consistent changes across many files at once. One pattern, many targets.

When to Use

✅ Good for:

• Renaming a function/component across all files that use it
• Adding an import to every file in a directory
• Updating version numbers across package files
• Applying the same code pattern to multiple similar files
• Migrating from one API to another across the codebase
• Adding/removing a field from all similar data structures

❌ Not for:

• Single-file edits (use direct editing)
• Unique changes per file (handle individually)
• Changes that need per-file judgment (use an agent per domain)

---

Batch Operation Protocol

Step 1: Define the Pattern

What:     [exact text/pattern to find]
Replace:  [exact replacement text]
Scope:    [file glob pattern, e.g., "src/**/*.tsx"]
Exclude:  [files to skip, e.g., "**/*.test.tsx"]

Step 2: Preview Before Executing

# Find all affected files FIRST
grep -rl "oldPattern" src/ --include="*.ts"

# Count matches
grep -rc "oldPattern" src/ --include="*.ts" | grep -v ":0$"

# Show context for each match
grep -rn "oldPattern" src/ --include="*.ts"

🔴 NEVER batch-modify without previewing first. Show the user what will change.

Step 3: Execute the Batch

For text replacements:

# On Linux/macOS
find src -name "*.ts" -exec sed -i 's/oldPattern/newPattern/g' {} +

# On Windows (PowerShell)
Get-ChildItem -Path src -Recurse -Filter *.ts |
  ForEach-Object { (Get-Content $_) -replace 'oldPattern','newPattern' | Set-Content $_ }

For structural changes (adding imports, wrapping code):

• Use the Edit tool on each file
• Process files in a consistent order (alphabetical or by dependency)

Step 4: Verify the Batch

# Confirm no missed instances
grep -rl "oldPattern" src/ --include="*.ts"
# Should return empty

# Confirm replacements are correct
grep -rn "newPattern" src/ --include="*.ts" | head -5

# Run tests to catch breakage
npm run test
npm run build

---

Common Batch Patterns

Operation	Command Pattern
Rename import	Find all import { X } → replace with import { Y }
Update version	Find "version": "1.0" → replace across all package.json
Add export	Append export { X } to all index files
Remove deprecated	Find deprecatedFn() → replace with newFn()
Add header	Prepend license header to all source files
Type migration	Find interface X → replace with type X =

---

Safety Rules

1. Preview first — always show affected files before modifying
2. Git safety — ensure clean working directory (git stash or commit first)
3. Exclude tests — often tests need different treatment than source
4. Verify after — run build + tests after every batch operation
5. Report changes — list every file modified with change summary