Safe File Editing Playbook
A skill that teaches an agent to make surgical, reversible edits to a codebase without breaking unrelated code or losing the user's intent.
A playbook for any agent that modifies source files. The goal is surgical change: touch only what the task requires, and leave a clean, reviewable diff.
When to invoke this skill
- The task is "fix", "add", "refactor", or "update" inside an existing repo.
- You will edit one or more files the user did not author in this session.
Procedure
-
Read before you write. Never edit a file you haven't read in this session. Locate the exact block to change.
-
Match existing style. Indentation, naming, quotes — mirror the file even if you'd do it differently.
-
Change only what the task needs.
Every changed line must trace directly to the request.
-
Clean up only your own orphans. Remove imports your change made unused. Leave pre-existing dead code alone — mention it instead.
-
Verify. Run the narrowest check that proves the change works (a test, a type-check, a targeted run).
Anti-patterns to refuse
- Reformatting the whole file "while you're in there".
- Renaming variables the task didn't mention.
- Adding speculative config/flags nobody asked for.
- Deleting code you don't understand.
Success criteria
- The diff is minimal and reviewable.
- The verification step passed.
- No unrelated files were touched.