Incremental Change Surgeon

The Problem

You ask your AI agent to change an error message in a 200-line auth module. It reads the file, decides the whole thing "could be cleaner," and regenerates the entire module with write_file. The new version changes import order, removes a comment your teammate added yesterday, reformats the logging calls, and subtly alters the exception class hierarchy. Three tests in test_auth.py now fail — not because of your change, but because the agent rewrote code it had no business touching. You spend 25 minutes debugging regressions that never should have existed. The actual change you wanted was two lines.

What You Get

• Scope assessment framework that forces four questions before any edit: What exactly needs to change? What's the blast radius? Can this be a targeted patch? What should NOT change? — ensuring every modification has explicit boundaries
• Tool selection matrix matching change size to the right operation: ≤5 lines → patch with exact string match, 5-30 lines → patch with surrounding context, >100 lines → write_file only when genuinely needed, multi-file changes → sequential patches one file at a time
• Guardrail execution protocol requiring read-before-edit (never edit from memory), exact string matching for patch old_string, test verification after every change, and automatic stop if a patch fails 3 times (re-read and reassess instead of falling back to write_file)
• Post-change verification checklist with diff audit (only intended lines changed), git status check (only intended files modified), full test suite run (not just the changed file), and self-audit ("Did I change anything not part of the request?")
• Anti-pattern catalog documenting the five most common failure modes: "I'll just rewrite to be safe," scope creep during refactoring, formatting changes mixed with functional changes, not reading before editing, and forgetting to update tests
• Quantified success metrics — typical surgical sessions save 15-30 minutes of regression debugging, achieve 80%+ patch-to-write_file ratio, and produce diffs reviewable in under 2 minutes

Why This Beats Prompting It Yourself

When you tell an agent "fix this bug," it optimizes for correctness of the output file — which means regenerating the entire file to guarantee consistency. But correctness of the output is not the same as correctness of the change. A full rewrite changes git blame, destroys reviewability, and introduces regressions in code that was working fine. This skill installs a decision framework that runs before every edit, defaulting to the minimum-power tool that achieves the goal. It's the difference between a surgeon using a scalpel and a demolition crew using a bulldozer.

Example Session

You: "The login error message says 'Invalid credentials' but it should say 'Invalid email or password' for the email field specifically."

Agent output (surgical approach):

SCOPE ASSESSMENT:
  What changes: Error message string on line 87 of auth.py
  Blast radius: test_auth.py::test_login_invalid_email (expects old string)
  Can patch: YES — ≤5 lines, single location
  Must not change: imports, constructor, logging, exception handling, all other tests

EXECUTION:
  1. Read auth.py line 87: "Invalid credentials"
  2. Patch auth.py: "Invalid credentials" → "Invalid email or password"
  3. Patch test_auth.py: update expected string in test assertion
  4. Run pytest test_auth.py — all pass

DIFF:
  auth.py: 1 line changed
  test_auth.py: 1 line changed
  Total: 2 lines across 2 files. Nothing else touched.

Use Cases

• Bug fixes in existing files where the agent tends to over-generate
• Feature additions that touch existing modules (add middleware, new config entry, dependency)
• Refactoring requests (extract method, rename, simplify) where scope creep is the main risk
• Configuration changes (package.json, pyproject.toml, CI configs) where accidental changes break builds
• Any task where the developer has experienced "the agent broke more than it fixed"

Known Limitations

This skill does not apply to brand-new file creation — if the file doesn't exist yet, write_file is the correct tool. For changes spanning >50% of a file or requiring restructuring across multiple classes, a full rewrite may genuinely be the better approach — the framework helps you make that decision consciously rather than defaulting to it. The skill is language-agnostic but assumes the agent has access to both patch and write_file tools.