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
npx skills add iSerter/laravel-claude-agents --skill laravel-systematic-debugging -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/laravel-systematic-debugging/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/laravel-systematic-debugging/
1Skills CLI (Vercel)
npx skills add iSerter/laravel-claude-agents --skill laravel-systematic-debugging -a codex2Manually: put the files in place
.agents/skills/laravel-systematic-debugging/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add iSerter/laravel-claude-agents --skill laravel-systematic-debugging -a cursor2Manually: put the files in place
.cursor/skills/laravel-systematic-debugging/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install iSerter/laravel-claude-agents skills/laravel-systematic-debugging2Manually: put the files in place
.github/skills/laravel-systematic-debugging/SKILL.md1Skills CLI (Vercel)
npx skills add iSerter/laravel-claude-agents --skill laravel-systematic-debugging -a gemini-cli2Platform CLI
gemini skills install https://github.com/iSerter/laravel-claude-agents --path skills/laravel-systematic-debuggingManually: put the files in place
.devin/skills/laravel-systematic-debugging/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add iSerter/laravel-claude-agents --skill laravel-systematic-debugging -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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