Performance Troubleshooting Flowchart

Documentation for Developers

🚑 Performance Troubleshooting Flowchart

Quick Reference Guide for Monorepo Issues

🚨 Emergency Response

Is Cursor/IDE Frozen?

❌ Cursor is frozen or unresponsive
    ↓
🔴 IMMEDIATE ACTION
    ↓
Terminal: yarn crash:nuclear
    ↓
Restart Cursor completely
    ↓
Terminal: yarn nx reset
    ↓
✅ Start fresh

🔍 Diagnostic Flowchart

Step 1: Identify the Problem

START: Something feels slow/wrong
    ↓
Run: yarn crash:check
    ↓
┌─────────────────────┐
│ What's the output?  │
└─────────────────────┘
         ↓
    ┌────┴────┐
    │         │
✅ Healthy   ⚠️ Warning/Critical
    │         │
    │         ↓
    │    Go to Step 2
    ↓
Continue working

Step 2: Check Specific Issues

⚠️ System has issues
    ↓
Check Activity Monitor / Top
    ↓
┌──────────────────────────────┐
│ What do you see?             │
└──────────────────────────────┘
         ↓
    ┌────┴────────────────┐
    │                     │
High CPU (>400%)    High Memory (>80%)
    │                     │
    ↓                     ↓
Go to CPU FIX       Go to MEMORY FIX
    │                     │
    │                     │
Too many processes    Build hanging
    │                     │
    ↓                     ↓
Go to PROCESS FIX   Go to BUILD FIX

🔧 Fix Procedures

CPU FIX: High CPU Usage (>400%)

# Quick Check
ps aux | grep -E "(node|tsserver|nx)" | grep -v grep | head -10

# If you see 10+ processes:
yarn crash:fix

# If still high CPU after 2 minutes:
yarn crash:nuclear

# Then restart Cursor

Root Causes:

Multiple NX daemons running
TypeScript server duplication
Stale build processes

Prevention:

# Run before starting work:
yarn crash:prevent

MEMORY FIX: High Memory Usage (>80%)

# Check memory usage
yarn perf:check

# Clear caches
yarn nx reset
rm -rf dist/ .nx/cache

# If persists:
yarn crash:nuclear

# Then rebuild:
yarn build:gograb:fast

Root Causes:

Build cache accumulation
Memory leaks in TypeScript server
Large dependency graphs

Prevention:

# Weekly cleanup:
yarn nx reset
rm -rf dist/

PROCESS FIX: Too Many Processes

# Count processes
ps aux | grep node | wc -l

# If >10 processes:
yarn crash:fix

# Check specific process types:
ps aux | grep "Cursor Helper" | wc -l   # Should be 2-4
ps aux | grep tsserver | wc -l          # Should be 1-2
ps aux | grep nx | wc -l                # Should be 1-2

# If any are high:
yarn crash:nuclear

Root Causes:

Process accumulation over time
Cursor extension memory leak
Failed build cleanup

Prevention:

# Every 30 minutes:
yarn crash:check

# Or run daemon:
./tools/scripts/setup-monitoring-daemon.sh

BUILD FIX: Build Hanging or Failing

# Kill stuck builds
yarn perf:cleanup

# Reset NX
yarn nx reset

# Try fast build
yarn build:gograb:fast

# If still hanging:
yarn crash:nuclear
yarn build:gograb:fast

# If critical:
export NODE_OPTIONS="--max-old-space-size=12288"
yarn build:gograb:fast

Root Causes:

TypeScript compilation hanging
Memory exhaustion
Circular dependencies

Prevention:

# Use optimized builds:
yarn build:gograb:fast        # Development
yarn build:gograb:optimized   # Production

📊 Health Check Interpretation

Health Score Meanings:

🟢 85-100% = HEALTHY
   Continue working normally
   Run preventive check weekly

🟡 60-84% = WARNING
   Some issues detected
   Action: yarn crash:fix
   Monitor closely

🟠 40-59% = CRITICAL
   Major issues detected
   Action: yarn crash:fix
   If persists: yarn crash:nuclear

🔴 0-39% = DANGER
   System unstable
   Action: yarn crash:nuclear
   Then restart Cursor

🎯 Quick Reference Commands

Health & Diagnostics:

yarn crash:check      # Check system health
yarn perf:check       # Check processes
yarn perf:report      # Full performance audit

Fixes:

yarn crash:fix        # Quick fix (minor issues)
yarn crash:prevent    # Preventive cleanup
yarn crash:nuclear    # Nuclear option (severe issues)

Monitoring:

yarn perf:monitor     # Monitor during build
yarn crash:monitor    # Continuous monitoring

Building:

yarn build:gograb:fast        # Fast dev build
yarn build:gograb:optimized   # Optimized build
yarn build:gograb:monitor     # Build with monitoring

🚦 When to Use What

🟢 Preventive (Daily)

# Before starting work:
yarn crash:prevent

# Every 30 minutes:
yarn crash:check

# Before leaving:
yarn crash:check

🟡 Reactive (When Issues Appear)

# IDE feels slow:
yarn crash:check

# High CPU:
yarn crash:fix

# Build failing:
yarn perf:cleanup
yarn nx reset

🔴 Emergency (Critical Issues)

# Cursor frozen:
yarn crash:nuclear
# Then restart Cursor

# Cannot build:
yarn crash:nuclear
yarn nx reset
yarn build:gograb:fast

# System unusable:
yarn crash:nuclear
# Restart Mac if needed

🔄 Maintenance Schedule

Daily:

Run yarn crash:prevent before work
Run yarn crash:check every 30 min
Monitor Activity Monitor occasionally

Weekly:

Run yarn perf:report
Run yarn nx reset
Clear dist/ directory
Check process counts

Monthly:

Full performance audit
Review health check logs
Update dependencies
Optimize new libraries

📱 Quick Diagnosis Table

Symptom	Likely Cause	Quick Fix	Command
Cursor slow	Multiple processes	Kill extras	`yarn crash:fix`
High CPU	NX daemon conflict	Reset daemon	`yarn crash:nuclear`
Build hanging	TypeScript stuck	Restart TS	`yarn perf:cleanup`
High memory	Cache bloat	Clear cache	`yarn nx reset`
Cannot build	Stale processes	Nuclear cleanup	`yarn crash:nuclear`
IDE crash	Resource exhaustion	Full reset	`yarn crash:nuclear` + restart

💡 Pro Tips

Best Practices:

✅ Run yarn crash:prevent EVERY day before starting
✅ Use yarn build:gograb:fast for development
✅ Restart Cursor every 2-3 hours
✅ Monitor Activity Monitor for high CPU
✅ Run health check if things feel slow

What NOT to Do:

❌ Don't run multiple builds simultaneously
❌ Don't ignore health check warnings
❌ Don't let processes accumulate
❌ Don't work for >3 hours without restart
❌ Don't skip weekly maintenance

Performance Habits:

# Morning routine:
yarn crash:prevent

# During work:
yarn crash:check  # Every 30 min

# Before lunch:
yarn crash:check

# End of day:
yarn crash:check

🆘 Still Having Issues?

Escalation Path:

Try basic fixes (5 minutes)
```
yarn crash:fix
```
Try nuclear option (10 minutes)
```
yarn crash:nuclear
# Restart Cursor
```

Full system reset (15 minutes)

yarn crash:nuclear
rm -rf node_modules dist .nx
yarn install
yarn build:gograb:fast

Last resort (30 minutes)

# Restart Mac
# Fresh Cursor start
yarn install
yarn nx reset
yarn build:gograb:fast

📚 Related Documentation

Remember: Prevention is easier than cure! Run yarn crash:prevent daily! 🛡️

Last Updated: October 20, 2025
Quick Help: Run yarn crash:check when in doubt!