> ## Documentation Index
> Fetch the complete documentation index at: https://docs.karpathy.phronesisagent.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Surgical Changes: edit only what the request requires
> Surgical Changes restricts every code edit to the exact lines required by the request. No drive-by refactoring, reformatting, or unrelated cleanup is permitted.
When you ask an LLM to fix a bug, you expect a focused diff. What you often get instead is a sweeping "improvement" that touches comments, reformats whitespace, adds type hints, upgrades validation logic, and restructures boolean returns — none of which you asked for. Surgical Changes enforces a simple discipline: every changed line must trace directly to the user's request, nothing more.
## Two rules
### Don't touch what you shouldn't
When editing existing code:
* Don't "improve" adjacent code, comments, or formatting
* Don't refactor things that aren't broken
* Match existing style, even if you'd do it differently
* If you notice unrelated dead code, **mention it — don't delete it**
### Clean up your own orphans
When your changes create unused artifacts:
* Remove imports, variables, and functions that **your** changes made unused
* Don't remove pre-existing dead code unless explicitly asked
## The test
Every changed line should trace directly to the user's request. If you can't answer "why did this line change?" with a direct reference to the task, the change shouldn't be there.
## Drive-by refactoring example
**Request:** "Fix the bug where empty emails crash the validator"
**What LLMs do wrong — "fixing" adjacent username logic, adding a docstring, improving email validation beyond the bug**
```diff theme={null}
def validate_user(user_data):
- # Check email format
- if not user_data.get('email'):
+ """Validate user data."""
+ email = user_data.get('email', '').strip()
+
+ # Validate email
+ if not email:
raise ValueError("Email required")
-
- # Basic email validation
- if '@' not in user_data['email']:
+ if '@' not in email or '.' not in email.split('@')[1]:
raise ValueError("Invalid email")
- # Check username
- if not user_data.get('username'):
+ # Validate username
+ username = user_data.get('username', '').strip()
+ if not username:
raise ValueError("Username required")
+ if len(username) < 3:
+ raise ValueError("Username too short")
+ if not username.isalnum():
+ raise ValueError("Username must be alphanumeric")
return True
```
Unasked-for changes: improved email validation, added username length and alphanumeric checks, changed comments, added a docstring.
**The correct approach — only the lines that fix the empty email crash**
```diff theme={null}
def validate_user(user_data):
# Check email format
- if not user_data.get('email'):
+ email = user_data.get('email', '')
+ if not email or not email.strip():
raise ValueError("Email required")
# Basic email validation
- if '@' not in user_data['email']:
+ if '@' not in email:
raise ValueError("Invalid email")
# Check username
if not user_data.get('username'):
raise ValueError("Username required")
return True
```
Only changed: the specific lines that fix empty email handling.
## Style drift example
**Request:** "Add logging to the upload function"
**What LLMs do wrong — changing quote style, adding type hints, adding a docstring, reformatting whitespace**
```diff theme={null}
- def upload_file(file_path, destination):
+ def upload_file(file_path: str, destination: str) -> bool:
+ """Upload file to destination with logging."""
+ logger.info(f"Uploading {file_path} to {destination}")
+
try:
- with open(file_path, 'rb') as f:
- data = f.read()
-
- response = requests.post(destination, files={'file': data})
-
- if response.status_code == 200:
- return True
- else:
- return False
+ with open(file_path, "rb") as f:
+ data = f.read()
+ response = requests.post(destination, files={"file": data})
+ success = response.status_code == 200
+
+ if success:
+ logger.info(f"Upload successful: {file_path}")
+ else:
+ logger.error(f"Upload failed: {file_path}, status={response.status_code}")
+
+ return success
except Exception as e:
- print(f"Error: {e}")
+ logger.exception(f"Upload error for {file_path}: {e}")
return False
```
Unasked-for changes: type hints, docstring, quote style changed from `'` to `"`, whitespace reformatted, boolean return logic restructured.
**The correct approach — match existing style, add only the logging lines**
```diff theme={null}
+ import logging
+
+ logger = logging.getLogger(__name__)
+
def upload_file(file_path, destination):
+ logger.info(f'Starting upload: {file_path}')
try:
with open(file_path, 'rb') as f:
data = f.read()
response = requests.post(destination, files={'file': data})
if response.status_code == 200:
+ logger.info(f'Upload successful: {file_path}')
return True
else:
+ logger.error(f'Upload failed: {file_path}, status={response.status_code}')
return False
except Exception as e:
- print(f"Error: {e}")
+ logger.exception(f'Upload error: {file_path}')
return False
```
Matched: single quotes, no type hints, existing boolean pattern, original spacing style.
## When this principle is working
* Diffs are small and focused — only requested changes appear
* PRs are clean with no drive-by refactoring or "improvements"
* Code style is consistent within each file, even across contributors
* Every line in the diff has an obvious reason for changing