Skip to main content
skill CX Codex

laravel-systematic-debugging — Claude Code skill for Laravel

The laravel-systematic-debugging skill guides an agent through investigating Laravel errors before changing code. Use it for failing tests, Eloquent issues, and unexpected application behavior.

MIT 110 installs ★ 48 updated 2026-04-19

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add iSerter/laravel-claude-agents --skill laravel-systematic-debugging -a claude-code
Open on GitHub

What laravel-systematic-debugging does

The skill lays out four phases. First, inspect error messages and logs, review recent changes, and reproduce the issue. Then compare the failing code with working examples and Laravel conventions. The agent forms one hypothesis and tests it with a minimal change. It must investigate before proposing a fix.

For implementation, the process calls for a failing test, one targeted change, and verification with tests and a manual check. If a fix fails, return to the investigation; after three failed attempts, question the approach itself. That keeps the agent from treating an obvious-looking patch as a confirmed solution. The examples use Laravel Telescope, php artisan, Tinker, and Laravel logs.

Install it in Claude Code with npx skills add iSerter/laravel-claude-agents --skill laravel-systematic-debugging -a claude-code. The skill is also listed for Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode, each with its own install command.

What it helps with

  • trace the cause of a failing Laravel test
  • investigate unexpected Eloquent query results
  • diagnose a queue, route, or migration failure
  • look into Laravel performance issues
  • verify a proposed fix with a focused test

Example prompts for the agent

  • Investigate why this Laravel test fails; identify the root cause before suggesting a change.
  • Trace this unexpected Eloquent result and test one specific hypothesis.
  • Debug this queue failure step by step, starting with evidence rather than a patch.

How to install laravel-systematic-debugging

1Skills CLI (Vercel)

npx skills add iSerter/laravel-claude-agents --skill laravel-systematic-debugging -a claude-code

2Manually: put the files in place

~/.claude/skills/laravel-systematic-debugging/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/laravel-systematic-debugging/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about laravel-systematic-debugging

How do I install laravel-systematic-debugging in Claude Code?

Run npx skills add iSerter/laravel-claude-agents --skill laravel-systematic-debugging -a claude-code. The skill file is at ~/.claude/skills/laravel-systematic-debugging/SKILL.md.

What does laravel-systematic-debugging do?

It gives an agent a four-phase Laravel debugging process: investigate the cause, compare patterns, test a hypothesis, then implement and verify a fix. It puts investigation ahead of code changes.

How does the skill verify a Laravel fix?

It calls for a test that reproduces the failure, one targeted change, and a test run afterward. If the fix fails, the process returns to investigation.

Source text

SKILL.md · MIT
---
name: laravel-systematic-debugging
description: Systematic debugging process for Laravel applications - ensures root cause investigation before attempting fixes. Use for any Laravel issue (test failures, bugs, unexpected behavior, performance problems).
---

# Systematic Debugging for Laravel

## Overview

Random fixes waste time and create new bugs in Laravel applications. Quick patches mask underlying issues.

**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

**Violating the letter of this process is violating the spirit of debugging.**

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```

If you haven't completed Phase 1, you cannot propose fixes.

## When to Use

Use for ANY Laravel technical issue:
- Test failures
- Eloquent query issues
- Authentication/authorization bugs
- Validation failures
- Queue job failures
- Route errors
- Migration issues
- N+1 query problems
- Performance issues

**Use this ESPECIALLY when:**
- Under time pressure
- "Just one quick fix" seems obvious
- You've already tried multiple fixes
- Previous fix didn't work
- You don't fully understand the issue

## The Four Phases

You MUST complete each phase before proceeding to the next.

### Phase 1: Root Cause Investigation

**BEFORE attempting ANY fix:**

1. **Read Error Messages Carefully**
   ```
   SQLSTATE[23000]: Integrity constraint violation
   → Check foreign key constraints, not a code bug
   
   Class 'App\Models\Post' not found
   → Check namespace, run composer dump-autoload
   
   Method Illuminate\Database\Eloquent\Collection::save does not exist
   → get() returns Collection, not Model. Use first() or update()
   ```

2. **Check Laravel Logs**
   ```bash
   # Main Laravel log
   tail -f storage/logs/laravel.log
   
   # Check for specific errors
   grep "SQLSTATE" storage/logs/laravel.log
   
   # Clear logs if too large
   > storage/logs/laravel.log
   ```

3. **Enable Debug Mode (Local Only)**
   ```env
   APP_DEBUG=true
   APP_ENV=local
   ```

4. **Use Laravel Telescope**
   ```bash
   composer require laravel/telescope --dev
   php artisan telescope:install
   php artisan migrate
   
   # Access at /telescope
   # View: Requests, Queries, Jobs, Events, Exceptions
   ```

5. **Check Recent Changes**
   ```bash
   # What changed that could cause this?
   git log --oneline -10
   git diff HEAD~5
   
   # Check if migrations ran
   php artisan migrate:status
   
   # Check if config cached
   php artisan config:show
   ```

6. **Reproduce Consistently**
   ```bash
   # Can you trigger it every time?
   php artisan tinker
   >>> App\Models\Post::first();
   
   # Try in different environments
   APP_ENV=testing php artisan test
   ```

7. **Trace Data Flow for Eloquent Issues**
   ```php
   // Enable query logging
   DB::listen(function ($query) {
       Log::debug('Query executed', [
           'sql' => $query->sql,
           'bindings' => $query->bindings,
           'time' => $query->time,
       ]);
   });
   
   // Or in specific code
   DB::enableQueryLog();
   $posts = Post::with('user')->get();
   dd(DB::getQueryLog());
   ```

### Phase 2: Pattern Analysis

**Find the pattern before fixing:**

1. **Find Working Examples in Laravel**
   ```bash
   # Search for similar working code
   grep -r "belongsTo" app/Models/
   grep -r "middleware" app/Http/
   
   # Check Laravel docs for the pattern
   # Check other models that work correctly
   ```

2. **Compare Against Laravel Conventions**
   ```php
   // ❌ What you have
   class Post extends Model {
       public function author() {
           return $this->hasOne(User::class, 'id', 'user_id');
       }
   }
   
   // ✅ Laravel convention
   class Post extends Model {
       public function user(): BelongsTo {
           return $this->belongsTo(User::class);
       }
   }
   ```

3. **Check Laravel Documentation**
   - Read the COMPLETE section, don't skim
   - Follow examples exactly first
   - Customize only after understanding

4. **Identify Differences**
   ```php
   // Working model
   class User extends Model {
       protected $fillable = ['name', 'email'];
   }
   
   // Broken model - difference: missing mass assignment protection
   class Post extends Model {
       // No $fillable or $guarded defined
   }
   ```

### Phase 3: Hypothesis and Testing

**Scientific method:**

1. **Form Single Hypothesis**
   ```
   Hypothesis: "Posts aren't saving because mass assignment 
   protection is blocking the 'user_id' field"
   
   Expected: Adding 'user_id' to $fillable will fix it
   ```

2. **Test Minimally**
   ```php
   // Before (broken)
   protected $fillable = ['title', 'content'];
   
   // Test change (ONE variable)
   protected $fillable = ['title', 'content', 'user_id'];
   
   // Don't change multiple things at once
   ```

3. **Verify in Tinker**
   ```bash
   php artisan tinker
   >>> $post = Post::create(['title' => 'Test', 'content' => 'Test', 'user_id' => 1]);
   >>> $post->user_id; // Should be 1
   ```

4. **When You Don't Know**
   - Say "I don't understand why X is happening"
   - Check Laravel GitHub issues for similar problems
   - Ask in Laravel Discord/Forums with specifics
   - Don't pretend to know

### Phase 4: Implementation

**Fix the root cause, not the symptom:**

1. **Create Failing Test Case**
   ```php
   use Illuminate\Foundation\Testing\RefreshDatabase;
   
   test('user can create post', function () {
       $user = User::factory()->create();
       
       $response = $this->actingAs($user)
           ->post('/posts', [
               'title' => 'Test Post',
               'content' => 'Test content',
           ]);
       
       $response->assertRedirect();
       
       expect(Post::where('title', 'Test Post')->exists())->toBeTrue();
       expect(Post::first()->user_id)->toBe($user->id);
   });
   
   // Run and watch it FAIL first
   php artisan test --filter=user_can_create_post
   ```

2. **Implement Single Fix**
   ```php
   // ONE fix for the root cause
   protected $fillable = ['title', 'content', 'user_id'];
   
   // NO bundled improvements like:
   // - Adding casts
   // - Refactoring methods
   // - Changing other code
   ```

3. **Verify Fix**
   ```bash
   # Test passes now
   php artisan test --filter=user_can_create_post
   
   # All tests still pass
   php artisan test
   
   # Manual verification
   php artisan tinker
   >>> $post = Post::create([...]);
   ```

4. **If Fix Doesn't Work**
   - STOP
   - Count: How many fixes have you tried?
   - If < 3: Return to Phase 1 with new information
   - **If ≥ 3: STOP and question the approach**

5. **If 3+ Fixes Failed: Question Architecture**
   ```
   Pattern indicating architectural problem:
   - Each fix reveals new shared state/coupling
   - Fixes require "massive refactoring"
   - Each fix creates new symptoms elsewhere
   
   STOP and question fundamentals:
   - Is this Laravel pattern correct?
   - Should we use a different approach (repository/service)?
   - Are we fighting the framework?
   
   Discuss with team before attempting more fixes.
   ```

## Laravel-Specific Debug Techniques

### Eloquent Debugging
```php
// See actual SQL
$posts = Post::where('status', 'published');
dd($posts->toSql(), $posts->getBindings());

// Check relationship loading
$post = Post::first();
$post->relationLoaded('user'); // false
$post->load('user');
$post->relationLoaded('user'); // true

// Prevent lazy loading (catch N+1)
Model::preventLazyLoading(!app()->isProduction());
```

### Route Debugging
```bash
# List all routes
php artisan route:list

# Find specific route
php artisan route:list --name=posts

# Check route exists
php artisan tinker
>>> route('posts.show', 1);
```

### Queue Debugging
```bash
# See failed jobs
php artisan queue:failed

# Retry failed job
php artisan queue:retry <id>

# Work queue with verbose output
php artisan queue:work --verbose

# Check job payload
php artisan tinker
>>> DB::table('jobs')->first();
```

### Validation Debugging
```php
// See exact validation errors
protected function failedValidation(Validator $validator)
{
    Log::debug('Validation failed', [
        'errors' => $validator->errors()->toArray(),
        'input' => $this->all(),
    ]);
    
    parent::failedValidation($validator);
}
```

## Red Flags - STOP and Follow Process

If you catch yourself thinking:
- "Quick fix for now, investigate later"
- "Just try changing X and see if it works"
- "Add protected $guarded = [] to see if that helps"
- "Skip the test, I'll manually verify"
- "It's probably the relationship definition"
- "I don't fully understand Eloquent but this might work"
- "The docs say X but I'll adapt it differently"
- **"One more fix attempt" (when already tried 2+)**

**ALL of these mean: STOP. Return to Phase 1.**

## Common Laravel Debugging Scenarios

### Scenario 1: N+1 Query Problem
```
Phase 1: Detect it
- Enable Model::preventLazyLoading()
- Exception thrown showing the problem

Phase 2: Find the pattern
- Check working code that uses with()
- Identify which relationship is lazy loading

Phase 3: Hypothesis
- "Adding with('user') will prevent the N+1"

Phase 4: Fix
- Add test that counts queries
- Add with('user') to the query
- Verify query count reduced
```

### Scenario 2: Route Model Binding Not Working
```
Phase 1: Investigate
- Check route definition: /posts/{post}
- Check controller parameter: Post $post
- Check if using custom key

Phase 2: Pattern
- Compare with working route binding
- Check Post model for getRouteKeyName()

Phase 3: Hypothesis
- "Parameter name doesn't match or model not found"

Phase 4: Fix
- Ensure route parameter matches method parameter
- Or customize: public function getRouteKeyName() { return 'slug'; }
```

### Scenario 3: Mass Assignment Exception
```
Phase 1: Error says "Add [field] to fillable property"
Phase 2: Check other models' $fillable arrays
Phase 3: Hypothesis: "Field not in $fillable"
Phase 4: Add field to $fillable, test
```

## Integration with Laravel Agents

- Use **laravel-debugger** for Laravel-specific debugging help
- Use **laravel-testing-expert** for creating failing tests (Phase 4)
- Use **eloquent-specialist** for relationship debugging
- Use **laravel-performance-optimizer** for performance issues

## Quick Reference

| Phase | Laravel-Specific Activities | Success Criteria |
|-------|----------------------------|------------------|
| **1. Root Cause** | Check logs, Telescope, Tinker, recent changes | Understand WHAT and WHY |
| **2. Pattern** | Find working Laravel examples, check docs | Identify differences |
| **3. Hypothesis** | Form theory, test in Tinker | Confirmed or new hypothesis |
| **4. Implementation** | Create Pest test, fix, verify | Bug resolved, tests pass |

## Remember

- Laravel has excellent error messages - read them fully
- Use Telescope for comprehensive debugging
- Tinker is your friend for testing hypotheses
- Follow Laravel conventions - fighting the framework causes bugs
- 95% of "weird Laravel behavior" is misunderstanding the framework

Always investigate systematically, understand the root cause, then fix once correctly.

© iSerter · MIT · iSerter/laravel-claude-agents

Similar skills

All skills for Code review and refactoring →

From the same set5

Project sponsors

Companies that keep this analytics open