batch-operations

[!IMPORTANT] AI Context & Knowledge Heritage

• Subsystem: Agent Skills Registry / batch-operations
• Architecture: @docs ARCHITECTURE:Documentation
• Failure Path: Information drift, legacy terminology, or documentation mismatch.
• Observability: Traceability via execution/parity_guard.py ([SKILL])

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)