Project Rescue

Project Rescue

Recovery playbook for vibecoders. When in doubt, start from Level 1 and escalate.

Quick Diagnosis

Ask: "What was the last thing you (or an AI) changed?" — this usually points to the problem.

Recovery Levels

Level 1: Soft Reset (Try First)

App won't start or shows errors after changes:

# Kill everything and restart
pkill -f node
npm run dev

Weird behavior, stale state:

# Clear caches
rm -rf .next .turbo .cache dist build .parcel-cache
npm run dev

"Module not found" or import errors:

rm -rf node_modules package-lock.json
npm install

Level 2: Undo Recent Changes

Undo last commit (keep changes as uncommitted):

git reset --soft HEAD~1

Discard ALL uncommitted changes (nuclear for files):

git checkout .
git clean -fd

See what changed recently:

git log --oneline -10
git diff HEAD~1

Level 3: Dependency Hell

Lock file conflicts or weird version issues:

rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Python equivalent:

rm -rf venv __pycache__ .pytest_cache
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt

Bun projects:

rm -rf node_modules bun.lockb
bun install

"But it works on the AI's machine": Check Node/Python version. Ask AI what version it assumed.

Level 4: Git Is Messed Up

Stuck in merge/rebase hell:

git merge --abort
# or
git rebase --abort

Detached HEAD (scary message, usually harmless):

git checkout main  # or master

Need to go back in time:

git log --oneline -20           # find the good commit hash
git checkout <hash>             # look around
git checkout -b rescue-branch   # save it if good

Complete git reset to remote (loses local changes):

git fetch origin
git reset --hard origin/main

Level 5: Nuclear Options

Start fresh but keep your code:

# Save your work
cp -r my-project my-project-backup

# Fresh clone
git clone <repo-url> my-project-fresh
cd my-project-fresh
npm install

Port already in use:

# macOS: Find what's using port 3000
lsof -i :3000
# Kill it
kill -9 <PID>

# Or kill all node processes
pkill -f node

Firebase/Supabase acting weird:

• Check the web console for the actual error
• Verify environment variables are set
• Check if you hit free tier limits

IDE-Specific Recovery

Cursor / Windsurf / VSCode

AI made a mess of files:

• Use Timeline (right-click file → Open Timeline) to restore previous versions
• Or: git diff HEAD to see changes, then git checkout <file> to restore specific files

Extensions causing issues:

• Disable all extensions, test, re-enable one by one

Replit

Project won't run:

1. Click "Shell" tab
2. Run kill 1 to restart the container
3. Or: npm install then npm run dev

Out of resources:

• Delete node_modules, .next, or other large folders
• Check storage usage in the Files pane

Common Vibecoding Disasters

macOS Specific

Clear system caches:

# Homebrew
brew cleanup

# npm global
npm cache clean --force

# Xcode (if iOS dev)
rm -rf ~/Library/Developer/Xcode/DerivedData

Node version issues:

# Check version
node -v

# Switch with nvm
nvm use 18   # or whatever version

Prevention Tips

1. Commit before big changes — git add . && git commit -m "checkpoint before X"
2. One change at a time — easier to undo
3. Read error messages — paste them to your AI, the answer is usually there
4. Check the browser console — right-click → Inspect → Console
5. Save working states — tag releases: git tag working-v1

When All Else Fails

1. Copy your important files (src/, components/, etc.) somewhere safe
2. Start a fresh project with the same stack
3. Move your files back piece by piece
4. Each piece that breaks tells you where the bug is