developersglobal/ai-agent-skills/surgical-changes

Overview

Every changed line is a line the reviewer must inspect, a line that could introduce a regression, and a line that will appear in the git blame forever. Unnecessary changes are costly.

AI agents often "improve" adjacent code, reformat files, rename variables for consistency, or delete "dead" code — all without being asked. This creates noisy diffs, unexpected behavior changes, and broken trust.

This skill enforces a hard rule: every changed line must trace directly to the user's request.

When to Use

• Any time you are modifying existing code (not creating new files)
• When your diff is larger than you expected
• When reviewing your own generated changes before presenting them

Process

Step 1: Establish the Change Boundary

1. Read the task carefully. Write down exactly which files and functions need to change.
2. Draw a mental boundary: "Everything outside this boundary is out of scope."
3. List what you will NOT change, even if you'd do it differently:

• Adjacent functions
• Variable naming conventions
• Comment style
• Import order
• Formatting/whitespace (unless fixing a specific bug)

Verify: You can name the specific functions/lines that need to change.

Step 2: Make Only the Required Changes

1. Make the changes — and only the changes — within the defined boundary.
2. If you notice something wrong outside the boundary:

• Mention it in a comment — don't fix it silently
• Example: "Note: I noticed `fetchUser` has no error handling, but I'm leaving that for a separate PR."

1. If your changes made imports/variables/functions unused: remove only those created by YOUR changes. Leave pre-existing dead code alone (unless asked).

Verify: No line changed that wasn't part of the defined scope.

Step 3: Review Your Own Diff

1. Read through your diff line by line.
2. For each changed line, ask: "Why did I change this?"

• If you can't answer → revert it

1. Flag any changes that are purely cosmetic and ask: "Should I include this?"

Verify: Every changed line has a clear reason directly tied to the task.

Step 4: Document Scope Decisions

1. In your PR/commit message, explicitly note what you chose NOT to change and why:

• "Did not refactor the adjacent `parseDate` function — out of scope for this fix."

Common Rationalizations (and Rebuttals)

Red Flags

• Your diff is 3× larger than the feature size suggests
• You changed files that aren't related to the task
• You reformatted a file "while you were there"
• You renamed variables for consistency
• You deleted comments or code you didn't fully understand
• Your PR description says "and also fixed a few other things"

Verification

• [ ] Every changed line traces to the task description
• [ ] No cosmetic-only changes bundled in (or explicitly approved)
• [ ] Pre-existing dead code left untouched (or flagged, not deleted)
• [ ] Changes to adjacent unrelated code: zero
• [ ] Diff size is proportional to task size

References

• simplicity-first skill
• code-review skill
• Karpathy: "They still sometimes change/remove comments and code they don't sufficiently understand as side effects, even if orthogonal to the task."