debugger

1. Collect symptoms → What is the observable behavior?
2. Review errors → Stack traces, logs, error messages
3. Establish timeline → When did it start? What changed?
4. Identify scope → Who/what is affected?
5. Check patterns → Is this recurring? Related to other issues?

1. List possible causes based on evidence
2. Rank by likelihood and impact
3. Design experiments to test each hypothesis
4. Start with most likely cause

1. Test hypothesis with minimal reproduction
2. Collect evidence (confirm or refute)
3. Move to next hypothesis if refuted
4. Document findings at each step

// Dump and die for quick inspection
dd($variable);

// Dump without stopping
dump($variable);

// Log to Laravel log
Log::debug('Checkpoint reached', ['data' => $data]);

// Query debugging
DB::enableQueryLog();
// ... code ...
dd(DB::getQueryLog());

// Tinker for interactive exploration
php artisan tinker

# Get last error from application
mcp__laravel-boost__last-error

# Read recent log entries
mcp__laravel-boost__read-log-entries(entries: 50)

# Read browser logs for frontend issues
mcp__laravel-boost__browser-logs(entries: 20)

# Execute diagnostic code
mcp__laravel-boost__tinker(code: "User::find(1)->toArray()")

# Query database directly
mcp__laravel-boost__database-query(query: "SELECT * FROM leads WHERE created_at > NOW() - INTERVAL 1 HOUR")

Cross-service correlation:
├── Error in Service A (12:01:03)
├── Timeout in Service B (12:01:05)
├── Database connection exhaustion (12:01:07)
└── Cascade to Service C, D (12:01:10)

Root cause: Service A retry storm exhausting connection pool

// N+1 Query Problem
// Symptom: Slow page load, many similar queries
// Fix: Eager loading
$leads = Lead::with(['lender', 'provider'])->get();

// Null Reference
// Symptom: "Trying to get property of non-object"
// Fix: Null checks, optional chaining
$name = $lead->lender?->name ?? 'Unknown';

// Race Condition in Cache
// Symptom: Intermittent wrong data
// Fix: Atomic operations, locks
Cache::lock('key')->block(seconds: 5, callback: function () {
    // Critical section
});

// Memory Exhaustion in Large Datasets
// Symptom: "Allowed memory size exhausted"
// Fix: Chunking, lazy collections
Lead::query()->lazy()->each(function ($lead) {
    // Process one at a time
});

1. Identify the first error in the chain (often NOT the loudest)
2. Map service dependencies
3. Trace error propagation path
4. Find the amplification point (retry storms, circuit breaker gaps)
5. Address root cause, then add circuit breakers

# Check application logs
tail -f storage/logs/laravel.log

# Monitor queue workers
php artisan horizon:status

# Check database connections
mysql -e "SHOW PROCESSLIST"

# Monitor memory usage
php -r "echo memory_get_usage(true);"

Problem: Lead processing failed
Why? → Database timeout
Why? → Query took too long
Why? → Missing index on created_at
Why? → Migration wasn't run
Why? → Deployment script skipped migrations
Root cause: Deployment process gap

Lead Not Processed
├── Input Invalid
│   ├── Missing required field
│   └── Invalid format
├── Processing Failed
│   ├── Database error
│   │   ├── Connection timeout
│   │   └── Constraint violation
│   └── External API failure
│       ├── Network error
│       └── Rate limited
└── System Error
    ├── Out of memory
    └── Queue worker crashed

// 1. Write failing test that reproduces the bug
it('handles concurrent lead updates', function () {
    // 🧪 Arrange
    $lead = Lead::factory()->create();

    // 🧪 Act - simulate concurrent access
    $results = collect([1, 2, 3])->map(fn () =>
        $this->patchJson("/api/leads/{$lead->id}", ['status' => 'processed'])
    );

    // 🧪 Assert - only one should succeed
    expect($results->where('status', 200)->count())->toBe(1);
});

// 2. Implement fix
// 3. Verify test passes
// 4. Check for side effects
// 5. Add monitoring

## Incident: [Title]

### Timeline
- [Time]: First error detected
- [Time]: Investigation started
- [Time]: Root cause identified
- [Time]: Fix deployed
- [Time]: Verified resolved

### Root Cause
[Clear explanation of what caused the issue]

### Impact
- Duration: X hours
- Users affected: X
- Data impact: [None/Description]

### Resolution
[What was done to fix it]

### Prevention
- [ ] Test added
- [ ] Monitoring added
- [ ] Documentation updated
- [ ] Process improved

### Lessons Learned
[What we'll do differently]

Issue: [Brief description]

Root Cause: [What actually caused it]

Evidence:
- [Log entry / stack trace]
- [Correlation with other events]
- [Pattern identified]

Fix: [What needs to change]

Prevention: [How to avoid recurrence]

Risk: [Impact of fix, rollback plan]