1Edits files by replacing text, creating new files, or deleting content. For moving/renaming use Bash 'mv'. For large edits use Write tool.
  2
  3<prerequisites>
  41. Use View tool to understand file contents and context
  52. For new files: Use LS tool to verify parent directory exists
  63. **CRITICAL**: Note exact whitespace, indentation, and formatting from View output
  7</prerequisites>
  8
  9<parameters>
 101. file_path: Absolute path to file (required)
 112. old_string: Text to replace (must match exactly including whitespace/indentation)
 123. new_string: Replacement text
 134. replace_all: Replace all occurrences (default false)
 14</parameters>
 15
 16<special_cases>
 17
 18- Create file: provide file_path + new_string, leave old_string empty
 19- Delete content: provide file_path + old_string, leave new_string empty
 20  </special_cases>
 21
 22<critical_requirements>
 23EXACT MATCHING: The tool is extremely literal. Text must match **EXACTLY**
 24
 25- Every space and tab character
 26- Every blank line
 27- Every newline character
 28- Indentation level (count the spaces/tabs)
 29- Comment spacing (`// comment` vs `//comment`)
 30- Brace positioning (`func() {` vs `func(){`)
 31
 32Common failures:
 33
 34```
 35Expected: "    func foo() {"     (4 spaces)
 36Provided: "  func foo() {"       (2 spaces) ❌ FAILS
 37
 38Expected: "}\n\nfunc bar() {"    (2 newlines)
 39Provided: "}\nfunc bar() {"      (1 newline) ❌ FAILS
 40
 41Expected: "// Comment"           (space after //)
 42Provided: "//Comment"            (no space) ❌ FAILS
 43```
 44
 45UNIQUENESS (when replace_all=false): old_string MUST uniquely identify target instance
 46
 47- Include 3-5 lines context BEFORE and AFTER change point
 48- Include exact whitespace, indentation, surrounding code
 49- If text appears multiple times, add more context to make it unique
 50
 51SINGLE INSTANCE: Tool changes ONE instance when replace_all=false
 52
 53- For multiple instances: set replace_all=true OR make separate calls with unique context
 54- Plan calls carefully to avoid conflicts
 55
 56VERIFICATION BEFORE USING: Before every edit
 57
 581. View the file and locate exact target location
 592. Check how many instances of target text exist
 603. Copy the EXACT text including all whitespace
 614. Verify you have enough context for unique identification
 625. Double-check indentation matches (count spaces/tabs)
 636. Plan separate calls or use replace_all for multiple changes
 64   </critical_requirements>
 65
 66<warnings>
 67Tool fails if:
 68- old_string matches multiple locations and replace_all=false
 69- old_string doesn't match exactly (including whitespace)
 70- Insufficient context causes wrong instance change
 71- Indentation is off by even one space
 72- Missing or extra blank lines
 73- Wrong tabs vs spaces
 74</warnings>
 75
 76<recovery_steps>
 77If you get "old_string not found in file":
 78
 791. **View the file again** at the specific location
 802. **Copy more context** - include entire function if needed
 813. **Check whitespace**:
 82   - Count indentation spaces/tabs
 83   - Look for blank lines
 84   - Check for trailing spaces
 854. **Verify character-by-character** that your old_string matches
 865. **Never guess** - always View the file to get exact text
 87   </recovery_steps>
 88
 89<best_practices>
 90
 91- Ensure edits result in correct, idiomatic code
 92- Don't leave code in broken state
 93- Use absolute file paths (starting with /)
 94- Use forward slashes (/) for cross-platform compatibility
 95- Multiple edits to same file: send all in single message with multiple tool calls
 96- **When in doubt, include MORE context rather than less**
 97- Match the existing code style exactly (spaces, tabs, blank lines)
 98  </best_practices>
 99
100<whitespace_checklist>
101Before submitting an edit, verify:
102
103- [ ] Viewed the file first
104- [ ] Counted indentation spaces/tabs
105- [ ] Included blank lines if they exist
106- [ ] Matched brace/bracket positioning
107- [ ] Included 3-5 lines of surrounding context
108- [ ] Verified text appears exactly once (or using replace_all)
109- [ ] Copied text character-for-character, not approximated
110      </whitespace_checklist>
111
112<examples>
113✅ Correct: Exact match with context
114
115```
116old_string: "func ProcessData(input string) error {\n    if input == \"\" {\n        return errors.New(\"empty input\")\n    }\n    return nil\n}"
117
118new_string: "func ProcessData(input string) error {\n    if input == \"\" {\n        return errors.New(\"empty input\")\n    }\n    // New validation\n    if len(input) > 1000 {\n        return errors.New(\"input too long\")\n    }\n    return nil\n}"
119```
120
121❌ Incorrect: Not enough context
122
123```
124old_string: "return nil"  // Appears many times!
125```
126
127❌ Incorrect: Wrong indentation
128
129```
130old_string: "  if input == \"\" {"  // 2 spaces
131// But file actually has:        "    if input == \"\" {"  // 4 spaces
132```
133
134✅ Correct: Including context to make unique
135
136```
137old_string: "func ProcessData(input string) error {\n    if input == \"\" {\n        return errors.New(\"empty input\")\n    }\n    return nil"
138```
139
140</examples>
141
142<windows_notes>
143
144- Forward slashes work throughout (C:/path/file)
145- File permissions handled automatically
146- Line endings converted automatically (\n ↔ \r\n)
147  </windows_notes>