Debugging Skill

You are systematically debugging an issue. Follow this structured approach — never brute-force retry the same thing. Every step narrows the search space.

Setup

Before starting: check .handoff/sessions/ for active sessions, read context status.yaml, run git status. Follow .rules/universal.md (Plan -> Approve -> Execute).

<!-- Rules loaded from .rules/universal.md -->

Process

Step 1: Reproduce

Before anything else, confirm the bug exists and is reproducible.

1. Get the error — Exact error message, stack trace, or unexpected behavior description
2. Get the context — When did it start? What changed recently? Which environment?
3. Reproduce locally — Run the failing command/test/request and capture the full output
4. If not reproducible — Check environment differences, data differences, timing/race conditions

Output: "I can reproduce this: {exact steps and output}" — OR — "Cannot reproduce. Need: {what additional info is required}"

Step 2: Isolate

Narrow down where the bug lives.

1. Check recent changes — git log --oneline -20, git diff for uncommitted work
2. Trace the execution path — Follow the request/data from entry point to failure
3. Binary search — If the codebase is large, bisect: does the bug exist in module A or B?
4. Check boundaries — Is the bug in our code, a dependency, the database, or the infrastructure?

Key questions:

• Does it fail with the simplest possible input?
• Does it fail in a different environment?
• Does reverting the last change fix it?
• Is it data-dependent?

Output: "The bug is in {file}:{line_range} because {evidence}"

Step 3: Diagnose

Understand the root cause, not just the symptom.

1. Read the code — Read the actual implementation, don't assume
2. Check assumptions — What does the code assume about inputs, state, ordering?
3. Look for common patterns:
   • Null/undefined access — Missing null checks, optional chaining needed
   • Race condition — Async operations completing in unexpected order
   • State mutation — Shared state modified unexpectedly
   • Type mismatch — String vs number, date formats, encoding
   • Off-by-one — Array bounds, pagination, date ranges
   • Missing migration — Database schema doesn't match model
   • Cache stale — OPcache, view cache, query cache serving old data
   • Environment mismatch — .env values, Docker config, service URLs
   • Dependency version — Breaking change in updated package

Output: "Root cause: {explanation of why the bug occurs}"

Step 4: Fix

Apply the minimal correct fix.

1. Fix the root cause — Not the symptom
2. Keep the fix minimal — Don't refactor unrelated code while debugging
3. Consider edge cases — Does the fix handle related scenarios?
4. Check for the same bug elsewhere — Grep for similar patterns in the codebase

Step 5: Verify

Confirm the fix works and doesn't break anything.

1. Reproduce the original bug — Confirm it no longer occurs
2. Run related tests — Not just the failing test, but adjacent tests
3. Check the happy path — Make sure normal operation still works
4. Test edge cases — Empty input, large input, concurrent access

Anti-Patterns (DO NOT)

• Don't retry the same command hoping for a different result
• Don't add random print statements without a hypothesis
• Don't fix the symptom and ignore the root cause
• Don't make multiple changes at once — change one thing, test, repeat
• Don't assume — read the actual code and actual error

Debug Output Format

# Debug Report: {Brief Description}

**Status:** FIXED | NEEDS_INFO | ESCALATE
**Time spent:** {duration}

## Symptom
{What the user reported / what failed}

## Root Cause
{Why it happened — the actual technical explanation}

## Fix Applied
{What was changed and why}
- File: {path} — {what changed}

## Verification
- [x] Original bug no longer reproduces
- [x] Related tests pass
- [x] No regressions in adjacent functionality

## Prevention
{How to prevent this class of bug in the future — test, lint rule, type check, etc.}

Framework-Specific Debug Guides

Laravel/PHP

• Check storage/logs/laravel.log for stack traces
• php artisan tinker to test in isolation
• php artisan route:list to verify route registration
• OPcache: restart container if code changes aren't picked up

Next.js/React

• Check browser console + network tab
• npm run build catches type errors that dev mode misses
• Server vs client component errors have different stack traces
• Check .next/ cache — rm -rf .next if stale

Docker

• docker compose logs {service} for container output
• docker compose exec {service} sh to inspect container state
• Check port mappings, volume mounts, environment variables
• Container restart picks up code changes when OPcache is active

Self-Assessment (Internal)

Rate this skill execution 0-10. If < 8, write feedback to .handoff/feedback/{date}-{skill-name}.yaml with: skill, rating, friction, suggestion, context. Do not mention to user.