Troubleshooting Guide

Emergency procedures when stuck, tests failing, or errors occurring. Use after 30+ minutes stuck on same issue.

Emergency Procedures

When Stuck (>30 min on one issue)

STOP IMMEDIATELY - Don't keep trying random solutions

Follow this process:

Document What You've Tried

• List all approaches attempted

• Note exact error messages

• Record what changed between working and broken states

Simplify & Isolate

• Can you reproduce in isolation? (minimal test case)

• Remove complexity: Comment out code until error disappears

• Bisect: Is it old code or new code causing the issue?

Check Fundamentals

• Are dependencies installed and up to date?

• Is configuration correct? (environment variables, paths)

• Are file permissions correct?

• Is the right version running? (restart server, clear cache)

Search for Similar Issues

• Google exact error message

• Check GitHub issues for dependencies

• Search Stack Overflow

• Review .claude/memory/ for similar past problems

Ask for Help

• Present clear problem statement to user:

• What are you trying to do?

• What happens instead?

• What have you tried?

• What's the exact error?

Record the Solution

• Once resolved, create .claude/memory/YYYY-MM-DD-issue-name.md

• Document: Problem, Root Cause, Solution, Prevention

When Tests Break Unexpectedly

Diagnosis Steps

Identify When It Broke

Check recent changes

git diff HEAD~1

Run tests on last commit

git checkout HEAD~1 npm test # or cargo test, pytest, go test

Isolate the Failing Test

Run single test file

npm test path/to/test.spec.ts

Run single test case

npm test -t "specific test name"

Check for Flakiness

• Run test 10 times: Does it fail consistently?

• Is it timing-dependent? (race condition)

• Does order matter? (test interdependence)

Recovery Process

If tests broke after your change:

Option 1: Revert and re-apply incrementally

git reset --hard HEAD~1

Re-apply changes one file at a time, testing after each

Option 2: Git bisect (find exact breaking commit)

git bisect start git bisect bad HEAD git bisect good <last-known-good-commit>

Git will checkout commits; run tests and mark good/bad

If tests broke without your changes:

• Check dependency updates (package-lock.json , Cargo.lock changes)

• Check environment differences (Node version, Python version)

• Check for flaky tests (run 10 times to confirm)

When Security Issue Found

PRIORITY: CRITICAL

Immediate Actions

DO NOT COMMIT vulnerable code

Stash changes if needed

git stash

Fix Immediately

• Security takes priority over all other work

• Apply fix from guardrails or security best practices

Add Regression Test

• Ensure vulnerability can't be reintroduced

• Test both the exploit and the fix

Document in Memory

• Create .claude/memory/YYYY-MM-DD-security-fix-NAME.md

• Document: Vulnerability, Impact, Fix, Prevention

Review Similar Code

• Search codebase for same pattern

• Fix all instances (not just the one found)

Common Security Issues & Fixes

SQL Injection:

// ❌ Vulnerable db.query(SELECT * FROM users WHERE id = ${userId});

// ✅ Fixed db.query('SELECT * FROM users WHERE id = ?', [userId]);

XSS (Cross-Site Scripting):

// ❌ Vulnerable element.innerHTML = userInput;

// ✅ Fixed element.textContent = userInput; // Or use framework escaping (React auto-escapes)

Hardcoded Secrets:

// ❌ Vulnerable const API_KEY = "sk_live_abc123";

// ✅ Fixed const API_KEY = process.env.API_KEY;

When Performance Degrades

Diagnosis

Measure First

• Don't guess - profile the code

• Use browser DevTools (frontend)

• Use profilers (cargo flamegraph , py-spy , pprof )

Identify Bottleneck

Node.js

node --prof app.js node --prof-process isolate-*.log

Python

python -m cProfile -o output.prof script.py python -m pstats output.prof

Go

go test -bench . -cpuprofile=cpu.prof go tool pprof cpu.prof

Common Culprits

• N+1 database queries (use eager loading)

• Large data loaded into memory (use pagination/streaming)

• Inefficient algorithms (O(n²) when O(n) possible)

• Missing indexes on database columns

• Unnecessary re-renders (React, Vue)

• Blocking I/O in async contexts

Fix Priorities

• Big wins first: Fix O(n²) → O(n), add database indexes

• Measure improvement: Benchmark before/after

• Don't over-optimize: 80% of time spent in 20% of code

When Build Fails

Common Issues

Dependency Conflicts:

Node.js

rm -rf node_modules package-lock.json npm install

Python

pip install --upgrade pip pip install -r requirements.txt --force-reinstall

Go

go clean -modcache go mod tidy go mod download

Rust

cargo clean cargo build

Version Mismatch:

• Check Node/Python/Go/Rust version matches project requirements

• Use version managers: nvm , pyenv , gvm , rustup

Missing Environment Variables:

Check .env.example vs .env

diff .env.example .env

Set required variables

export DATABASE_URL="..." export API_KEY="..."

When Git Issues Occur

Merge Conflicts

Show conflicted files

git status

Open files, look for conflict markers:

<<<<<<< HEAD Your changes

Their changes

branch-name

Resolve manually, then:

git add <resolved-files> git commit

Accidentally Committed Secrets

CRITICAL - Act immediately:

Remove from last commit (if not pushed)

git reset HEAD~1

Remove secret from file

Add file to .gitignore

git add . git commit -m "Remove secrets"

If already pushed - rotate the secret immediately

Then use BFG Repo-Cleaner or git-filter-branch

Lost Work

Find lost commits

git reflog

Recover lost commit

git checkout <commit-hash>

Create branch from recovered commit

git checkout -b recovery-branch

Red Flags (Stop & Reassess)

Stop immediately if you encounter these:

Code Red Flags

• ❌ Same error after 3 different attempted fixes

• ❌ Solution getting more complex instead of simpler

• ❌ Not understanding why a fix works ("it just works now")

• ❌ Touching >10 files for a "simple" bug fix

• ❌ Breaking existing tests to make new code work

Process Red Flags

• ❌ Skipping tests because "I'll add them later"

• ❌ Committing commented-out code "just in case"

• ❌ Ignoring linter errors "they're not important"

• ❌ Using any or unsafe to "make TypeScript/Rust happy"

• ❌ Copying code without understanding it

When you see red flags:

• STOP adding more code

• Revert to last working state

• Apply COMPLEX mode: Full 4D decomposition

• Ask user for guidance if still stuck

Common Error Messages & Solutions

TypeScript/JavaScript

"Cannot find module"

npm install

or

npm install <package-name>

"Type 'X' is not assignable to type 'Y'"

• Check type definitions: Are they correct?

• Use type assertions only if you're certain: as Y

• Consider using unknown and narrowing

"Module not found" (frontend)

• Check import paths (case-sensitive)

• Restart dev server

• Clear build cache

Python

"ModuleNotFoundError"

pip install -r requirements.txt

Or

pip install <module-name>

"IndentationError"

• Use consistent indentation (spaces vs tabs)

• Configure editor to use 4 spaces

"AttributeError: ... has no attribute ..."

• Check object type (use type() or debugger)

• Check if attribute exists (hasattr() )

Go

"cannot find package"

go mod tidy go mod download

"undefined: ..."

• Check imports

• Check if function/variable is exported (capitalized)

Rust

"cannot borrow x as mutable"

• Only one mutable borrow allowed

• Consider refactoring to avoid simultaneous borrows

"use of moved value"

• Value was moved (ownership transferred)

• Clone if needed, or use borrowing (& )

Recovery Checklist

After resolving any major issue:

• Tests passing

• Guardrails validated

• Root cause understood (not just symptom fixed)

• Documented in .claude/memory/ if significant

• Similar code reviewed for same issue

• Prevention added (test, linter rule, guardrail)

Remember: Being stuck is normal. Following a systematic process beats random attempts. Document your solutions - future you will thank you!