# Mechanical Batch Work — Script vs Per-File Edit

A "mechanical batch" is work where the same edit is applied to N files mechanically, with no per-file judgement after the pattern is established. Examples from prior sessions: declaring `practices: [slug]` across 533 cli/ Go files, regenerating COMMANDS.md from a Cobra tree, bumping a version literal in N manifests.

The default per-file `Edit` tool path scales linearly with N and burns context. Switch to a script when ANY of these apply:

- N > ~20 files
- The transformation is **uniform** (same regex / same sed / same template field)
- A failure on file K does not change the strategy for files K+1..N
- Per-file output verification is cheap (`git diff --stat`, a single grep)

## Script-first pattern

```bash
# 1. Inventory candidates with the predicate the task implies
candidates=$(git ls-files 'skills/**/SKILL.md' | xargs -I{} bash -c '
  grep -L "^practices:" "{}" >/dev/null && echo "{}"
' | head -50)

# 2. Apply the mechanical edit
for f in $candidates; do
  awk '
    /^description:/ && !done { print; print "practices: [<slug>]"; done=1; next }
    { print }
  ' "$f" > "$f.tmp" && mv "$f.tmp" "$f"
done

# 3. Verify in one shot
git diff --stat
grep -c "^practices:" $candidates | sort
```

## Per-file Edit pattern (when the above does NOT apply)

Use `Edit` per file only when:

- The transformation requires per-file decisions (which slug? which carrier?)
- N is small (< 10)
- Verification benefits from reading each diff in context

## Decision in Step 4

When `/rpi` discovery surfaces a per-file pattern with N > 20 uniform candidates, the implementation phase should generate a script under `scripts/` or use an inline awk/sed pass rather than queuing N `Edit` operations. The post-edit gate then verifies the batch atomically.

If the script needs different parameters per file, that is a signal the work isn't actually mechanical — fall back to per-file Edit and reduce N (split the cycle).

## Why this matters

A 533-file `practices:` backfill done via per-file Edit takes ~50× more context than the same backfill done via a script with `git diff --stat` verification. The context-budget exhausts well before the work completes, and the loop drops into a forced scout or idle state with most of the work still pending.

## Anti-patterns

- Running a script that mutates files but ignoring the result of `git diff` (silent partial application).
- Using `sed -i` on a tree-traversed find without `--null` handling (filename-with-spaces breakage).
- Mixing mechanical and per-file edits in the same commit (auditor cannot tell what was bulk-applied vs per-judged).
- Treating a 200-file batch as a single "atomic" change — split into review-sized waves (~30-100 files) with one commit per wave.