initial: pi-setup workspace with skill + extension plan

2026-06-10 17:30:43 +08:00
commit 49e581247b
158 changed files with 28777 additions and 0 deletions
@@ -0,0 +1,56 @@
+# 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.