Stats
Actions
Tags
From skeleton-skills
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. Follows 4 systematic phases (reproduce, root cause, hypothesis, fix) with stack-specific tools for Laravel and Next.js.
How this skill is triggered — by the user, by Claude, or both
Slash command
/skeleton-skills:skeleton-debuggingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Systematic 4-phase debugging adapted to the project's stack. Never jump to fixes without reproducing first.
Systematic 4-phase debugging adapted to the project's stack. Never jump to fixes without reproducing first.
Announce: "Using skeleton:debugging to systematically investigate this issue."
Execution environment: PHP is NOT available on the host.
All artisan commands must use: ./vendor/bin/sail artisan {command}
All composer commands must use: ./vendor/bin/sail composer {command}
Running bare php artisan or composer will fail immediately.
cd backend && ./vendor/bin/sail artisan test --filter={RelevantTest} or manual requestcd frontend && npm run test or reproduce in browserTrace the complete flow per architecture:
Backend flow: Request → Route → Controller → FormRequest → Policy → Action → Service/Contract → Model → Response
Backend tools:
dd() — dump and die at any pointDB::listen(fn ($q) => logger($q->sql)) — log all queries./vendor/bin/sail artisan tinker — interactive REPL./vendor/bin/sail artisan pail — live tail logsFrontend flow: User action → Component → Hook → api.ts → http-client → Response handling → State update → Re-render
Frontend tools:
console.table(queryClient.getQueryCache().getAll().map(q => ({ key: q.queryKey, state: q.state.status }))) — dump all query statesIdentify the exact layer where behavior diverges
git commit -m "fix(mod): description of fix"| Agent's excuse | Reality |
|---|---|
| "I already know what it is, let me fix it directly" | Systematic: 15-30 min. Random fixes: 2-3 hours of thrashing. Reproduce first. |
| "I don't need to reproduce it, the error is clear" | If it's clear, reproducing takes 1 minute. If you can't reproduce it, you don't understand the bug. |
| "Let me just try something quick" | "Something quick" × 5 = an hour wasted without evidence. Reproduce and trace first. |
| "I can't write a test for this bug" | If you can't test the bug, you can't verify the fix. Find how to test it. |
| "It's a configuration bug, not code" | Configuration CAN be reproduced and tested. .env, config/, phpunit.xml are files like any other. |
| "The bug only happens in production" | Reproduce the environment: env vars, test data, config. If you can't reproduce locally, ask for logs. |
| "The stack trace points to the library, not our code" | Our code CALLS the library. The bug is in HOW we call it. Trace our call. |
| "This is probably a race condition" | Race conditions are reproducible with proper setup. Don't use "probably" — verify with evidence. |
Bug: "Creating a sale doesn't decrement stock"
Phase 1: POST /api/sales → sale created, stock unchanged
Phase 2: Trace: Controller → CreateSaleAction → inventory->reserve() NOT CALLED
Phase 3: Hypothesis: "Action doesn't call reserve()"
Test: it('decrements stock when sale is created') → FAIL ✓
Phase 4: Add $this->inventory->reserve() → PASS ✓
Full suite → ALL PASS ✓
Commit: "fix(sales): call inventory reserve on sale creation"
Bug: "Creating a sale doesn't decrement stock"
1. ❌ "I bet it's the InventoryService" → changes InventoryService randomly
2. ❌ Still broken → changes the Controller
3. ❌ Still broken → adds dd() everywhere without reading the flow
4. ❌ 45 minutes later, still no fix, code is messy with debug statements
| Condition | Destination |
|---|---|
| Root cause identified, fix needs plan | skeleton:designing (for multi-file fix) |
| Simple fix (1-2 files) | Execute Phase 4 directly, then skeleton:validating |
| Bug is unresolvable | Escalate to human with all evidence |
npx claudepluginhub juanguillenmartinez/skeleton-skills --plugin skeleton-skillsOrchestrates a full debug pipeline: investigates a bug, diagnoses root cause, writes failing tests, implements fix via TDD, and reviews the result. Supports auto-commit and git worktrees.
Methodical 4-phase debugging process for resolving errors, test failures, and unexpected behavior systematically.
Diagnoses failures, fixes bugs, and investigates failing tests using systematic debugging: reproduce first, read before changing, assume nothing, find root cause.