laravel-systematic-debugging
This skill guides you through a four-phase debugging methodology designed to eliminate guesswork when troubleshooting Laravel issues. By enforcing root cause investigation before any fix attempt, it helps you avoid symptom-masking patches that create new problems. The process covers log analysis, Laravel Telescope inspection, data flow tracing, pattern comparison, hypothesis testing, and test-driven implementation.
Laravel Systematic Debugging provides a four-phase structured process to find root causes before fixing any Laravel issue.
AI-generated summary based on this skill's SKILL.md
Install
iSerter/laravel-claude-agents/laravel-systematic-debugging · repository language: PHP
git clone https://github.com/iSerter/laravel-claude-agents
cp -r laravel-claude-agents/skills/laravel-systematic-debugging ~/.claude/skills/laravel-systematic-debuggingnpx skillfed install iSerter/laravel-claude-agents/laravel-systematic-debuggingFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to debug Laravel applications systematically?
laravel-systematic-debugging guides you through a four-phase methodology that eliminates guesswork. Start by gathering context—check logs, inspect Laravel Telescope, and trace data flow. Then isolate the problem by comparing expected vs. actual behavior and forming testable hypotheses. Before applying any fix, create a failing test to verify the issue exists. Finally, implement your fix and confirm tests pass without breaking other code. This approach avoids quick patches that mask symptoms rather than solving root causes.
What's the laravel-systematic-debugging process for root cause investigation?
laravel-systematic-debugging enforces a structured four-phase process: (1) Gather—collect logs, use Telescope to inspect queries and requests, trace data flow through your code; (2) Isolate—compare what you expected vs. what actually happened, form specific hypotheses; (3) Test—write a failing test that reproduces the bug before fixing anything; (4) Fix & Verify—implement your solution and confirm all tests pass. This prevents symptom-masking patches and ensures fixes address actual problems, not just surface errors.
How do I fix Laravel test failures and bugs properly?
laravel-systematic-debugging teaches you to avoid random fixes by following Laravel conventions and testing hypotheses first. When a test fails, don't guess—gather evidence using logs and Telescope, isolate the root cause by comparing expected behavior to actual behavior, then write a test that reproduces the bug. Only after your test fails should you implement a fix. Verify that your fix makes the test pass and doesn't break other tests. This test-driven approach ensures you're solving the real problem, not just making the error go away.
What laravel-systematic-debugging techniques help with Eloquent query debugging?
laravel-systematic-debugging covers Eloquent debugging through structured tracing: use Laravel Telescope to inspect queries and spot N+1 problems, enable query logging to see actual SQL, and use Tinker to test relationships interactively. Trace data flow from your controller through models to understand where queries execute. Form hypotheses about missing eager loads or incorrect relationships, then write tests to verify. This prevents lazy-loading surprises and ensures your queries are optimized before deployment.
How to use Laravel Telescope for debugging?
laravel-systematic-debugging emphasizes Laravel Telescope as a core investigation tool. Telescope captures requests, queries, logs, and exceptions in real time. Use it to inspect Eloquent queries and spot N+1 problems, trace request flow through your application, and review error context. When debugging, open Telescope, reproduce the issue, then examine the captured data—queries show you what's actually running, request tabs show middleware and controller execution, and logs reveal application state. This structured inspection replaces guesswork with concrete evidence.
Why should I avoid quick fixes and follow laravel-systematic-debugging instead?
laravel-systematic-debugging prevents the trap of symptom-masking patches that create new problems. Quick fixes often hide root causes—you silence an error without understanding why it occurred, then face cascading failures later. The systematic approach enforces root cause investigation first: gather evidence, isolate the actual problem, test your hypothesis, then implement a fix. By creating failing tests before fixing, you ensure your solution addresses the real issue and doesn't break other code. This takes slightly longer upfront but saves debugging time and prevents production surprises.
SKILL.md
rendered from the published skill — quoted content, verbatim
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
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
skills/laravel-systematic-debugging/SKILL.md