No Scripted Editing

No scripted editing

A file edit made by a script is invisible. The person supervising the work sees a heredoc and a success message; they do not see what changed. The edit tools exist because the change itself is the thing that needs reviewing, and routing around them removes the review while keeping the risk.

This is a rule about traceability rather than about shell scripting. Shell is fine. Rewriting tracked files with it is not.

The rule

Read the file, then change it with the file editing tools. One edit, one visible diff.

If a change is too large or too repetitive for that to feel reasonable, that feeling is not a licence to script it. It is a signal to write the whole file deliberately, or to stop and agree on an approach first.

What counts as scripted editing

| Pattern | Why it is banned | | --- | --- | | sed -i / perl -pi -e | Rewrites in place with no diff, and exits 0 when the pattern matches nothing | | python3 -c or a heredoc calling write_text, open(...,'w') | Arbitrary rewrite behind a script the reviewer never reads | | node -e / bun -e writing files | Same, in a different language | | awk piped back over its own input | Same, plus a truncation risk | | > file or tee file onto tracked source | Replaces contents with nothing shown | | A throwaway script written, run, then deleted | Deliberately leaves no trace of what ran |

The language does not matter. The test is whether a file under version control changed without a diff being shown.

Three specific failures this prevents

Silent misses. A replacement whose pattern does not match changes nothing and still succeeds. The script prints its confirmation, the summary claims the edit landed, and the file is untouched. Reported success with no change is worse than an error, because nobody goes looking.

Unintended matches. A pattern written from memory, against a file that was never read, matches somewhere it was not meant to. String replacement has no idea what a function boundary is.

A defeated harness. File-state tracking, staleness checks, permission prompts, and formatting hooks are all keyed to the edit tools. A script bypasses every one of them, including the check that refuses an edit when the file changed underneath you.

What is still fine

• Reading and searching with anything: grep, rg, awk, jq, python. Inspection is not the problem.
• Creating genuinely new artifacts that nobody hand-maintains: build output, generated images, exports, fixtures.
• Anything under a scratch or temp directory, outside the repository.
• Tools the project already owns and sanctions: a formatter, a linter with a fix flag, a package manager, a codegen step defined in the project's own scripts. These are reviewed conventions, not improvised rewrites.
• Version control itself: git checkout, git revert, git apply on a patch that was shown first.

When a script genuinely is the right tool

Occasionally it is. A rename across two hundred files is a real codemod, and doing it by hand is worse.

The rule then is not "no script," it is "no invisible script":

1. Say what needs changing and why a script is the right instrument.
2. Write it as a file that can be read, not a heredoc that vanishes.
3. Get agreement before running it.
4. Run it, then show the resulting diff and the verification.

The script becomes a reviewable artifact instead of a hidden action. That satisfies the actual requirement, which is that nothing lands unseen.

What to do instead

A large edit. Write the complete file. A full rewrite is reviewable; a regex against it is not.

The same change in several places. Separate edits, or one replace-all through the edit tool, which reports how many occurrences it touched. The count is the verification.

A change across many files. Handle them one at a time, or treat it as a codemod under the process above. Many files is the case where a silent miss is least likely to be noticed, so it deserves more visibility rather than less.

A change you are unsure of. Read the file first. Most of the appeal of scripting comes from not having read the thing being changed.

Using this rule well

The cost is real and worth paying. Individual edits are slower than one clever substitution. The speed of a scripted rewrite is borrowed against the review that is no longer possible, and the interest comes due when something lands wrong and nobody can see where.

It is not a ban on shell. Inspection, building, testing, and running things are all normal. Confusing this rule for shell avoidance produces worse work, not safer work.

Generated files are the genuine grey area. Something checked into the repository but produced by a tool is tracked and not hand-maintained at once. Follow the project's convention: if it is regenerated by a command the project defines, run that command. If people edit it directly, treat it as source.

A formatter is still a bulk rewrite. It touches many files with no per-file diff shown, and it is allowed because the project chose it and its behavior is predictable and reversible. That reasoning is what makes it acceptable, so do not stretch it to cover an improvised script.

Watch for the honest-looking wrapper. Writing a small script that prints what it changed still fails the rule if nobody reads the script. Output the model wrote about its own action is not a diff.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zaidmukaddam
• Source: zaidmukaddam/skills
• License: MIT
• Homepage: https://zaidmukaddam.com/skill

Install and usage instructions live in the source repository linked above.