| name | diff |
| description | Generate and apply structured code changes to a file |
| tags | ["editing","code"] |
| tools_required | ["read_file","write_file"] |
| parameters | [{"name":"file","type":"string","description":"Path to the file to modify","required":true},{"name":"changes","type":"string","description":"Description of desired changes","required":true}] |
| output_format | text |
Diff — Structured File Editing
Read a file, plan precise changes based on a natural-language description, and apply them.
Steps
-
Read the file: Use read_file to load the full contents of {file}. Note the total line count and language/format.
-
Understand context: Before making changes, understand the file's purpose, its imports/dependencies, and how the section you are modifying fits into the broader structure.
-
Plan changes: Based on the instruction ({changes}), identify the minimal set of edits needed. For each edit, note:
- The line range affected
- What the current code does
- What the replacement code should do
- Any side effects on other parts of the file (imports, type hints, tests)
-
Generate a unified diff: Produce the changes as a unified diff (--- a/file, +++ b/file, @@ line ranges @@). Include enough context lines (3+) for each hunk to make the diff unambiguous.
-
Apply the changes: Use write_file to write the modified file contents. The written file must be the complete, final version -- not a partial patch.
-
Verify: Re-read the file with read_file to confirm the write succeeded and the content matches expectations. Check that:
- No syntax errors were introduced (matching brackets, quotes, indentation)
- Import statements are still valid
- The change matches the requested description
-
Report: Respond with:
- The unified diff showing what changed
- A brief summary of the modifications
- Any warnings about potential side effects (e.g., callers that may need updating)
Guidelines
- Make the smallest change that satisfies the request. Do not refactor unrelated code.
- Preserve the existing code style (indentation, quote style, naming conventions).
- If the requested change is ambiguous or could break functionality, explain the ambiguity before proceeding.
- Never silently delete code -- if removal is needed, call it out explicitly.