🔧 Karpathy AutoFix
A Self-Correcting Agent Loop for Fixing Bugs and Improving Codebases
When something is broken, this skill makes Claude investigate deeply, propose a fix, test it, self-correct on failure, and iterate — until it works or it hits an honest hard stop.
🤖 Claude Code
🔄 Self-Correcting
🖥️ CLI-First
🐛 Debugging
📅 April 2026
The Core Loop
INVESTIGATE
→
PLAN
→
ACT
→
VERIFY
→
PASS ✓
|
FAIL → self-correct → repeat
Hard rule: Never claim a fix worked without verification. Never stop prematurely if the issue persists. If it can't reproduce or fix the issue, it says so — no false confidence.
Step 1 — Clarifying Questions (Ask First)
Before writing any code, Claude asks just enough to reproduce and verify the fix:
Q1
What is the exact error or broken behavior?
Q2
What did you do when it happened?
Q3
What platform / OS / environment are you on?
Q4
What does "fixed" look like to you?
Q5
Any recent changes — new deps, config changes, git updates?
Why these questions matter: A vague "it doesn't work" is the #1 reason fixes fail. If Claude can't reproduce the error, it can't verify the fix. These 5 questions close that gap fast.
Step 2 — Investigate
- Reproduce the error — confirm the exact error message, input, and conditions that triggered it
- Read the relevant code — trace from the error site up the call stack, not just the error line
- Check the environment — Node version, Python version, OS, dependency state, git status
- Ask: is this the root cause or a symptom? — symptoms have many causes; root cause has one
- Search web for the error — paste the exact error text, read at least 2 sources before acting
⚠️ If you cannot reproduce the error, you cannot verify a fix. Reproduce first, always. If Thota gives a vague complaint ("it's broken"), ask the clarifying questions before assuming anything.
Step 3 — Plan
Answer these before editing anything:
- What file(s) need to change?
- What is the minimal change that fixes this?
- What else might this change break?
- What test or manual check will prove it works?
State the root cause and fix in one sentence. If you can't, go back to investigate more.
Step 4 — Act
- Make one change at a time. Verify after each.
- One file at a time is better than a big blast of changes.
- If the plan requires touching more than 3 files, reconsider.
- Use
git checkout -- <file> to revert cleanly if a change feels wrong.
# Revert a file cleanly
git checkout -- path/to/file.js
Step 5 — Verify
Run the exact command or input that produced the error. If it now succeeds → you're done. If it still fails → loop back to Step 2.
✅ Fixed when: the same input that triggered the error now produces the correct output — without any other changes to the system.
Self-Correction Rules
| Signal | Response |
|---|
| Test fails after fix | Re-read error, look at what changed, find the next failure point |
| Same error after change | Wrong root cause — go back to investigate |
| New error introduced | Revert last change, re-diagnose before continuing |
| Build fails | Fix build errors one at a time, in order |
| Can't reproduce | Stop. Report what you tried. Ask Thota for more context |
| Fix works but reason is unclear | Document why it works before declaring done |
| 3 attempts, none worked | Stop. List all attempts and ask for more context |
What To Do When a Fix Fails
- Error persists after fix: Wrong root cause. Revert. Go back to investigate more carefully.
- Error changed to a new error: The change introduced a new bug. Revert immediately.
- Build succeeds but tests fail: Business logic is wrong, not the build system.
- Error is intermittent: Race condition or non-deterministic behavior. Look for timing, async, or global state issues.
- "X is not a function" or "X is undefined": Wrong import, wrong version, or module didn't export what you expected. Check the actual export.
- Error is in a dependency: Don't modify
node_modules/ or vendor code. Fix is: upgrade, downgrade, or patch with a wrapper.
- Works in dev but not prod: Environment difference. Check Node/Python version, env vars, file paths, dependency versions.
Hard Stops
Stop and report to Thota immediately when:
- You need to delete or overwrite files outside the project scope
- A fix requires admin/root privileges that aren't available
- The fix would require changing a dependency's source code directly
- You've spent more than 20 minutes with no progress and still can't reproduce
⚠️ Stop is not failure. Reporting what you tried honestly is better than guessing. Thota would rather know it needs more context than have Claude spin in circles.
Fix Report Template
After every completed fix, Claude reports:
Problem: [what was broken]
Root cause: [what caused it]
Fix: [what changed]
Verified: [how you confirmed it works]
On "Improve This Project" (Not a Specific Bug)
- List all issues found, ranked by severity (critical / high / medium / low)
- Ask Thota which to tackle first
- Apply the same loop: plan → act → verify → report per item
- Never make unplanned changes to "improve" code that isn't broken
Why This Works — Karpathy Philosophy
- Minimal tools, maximum transparency. Every step is explicit. The agent never assumes — it reads, executes, observes, decides.
- The loop is the methodology. Observe → think → act → observe → repeat. No shortcuts.
- Terminal-first, no GUI. Claude Code is a CLI tool. The best tools are the ones you can script.
- Git as undo.
git checkout -- <file> reverts cleanly. No fear of experimenting.
- Explain the fix in one sentence. If you can't, the fix is too complex.
The key insight: Most debugging failures happen because the investigator stops too early. The AutoFix loop forces Claude to stay in investigation mode until the evidence is overwhelming — not just until it has a hypothesis.