debug-issuelisted

Use the moment a user reports something broken or behaving unexpectedly — a bug, failing or flaky test, crash, exception, stack trace, regression, build break, or integration failure — and use it BEFORE the first command you would run to investigate, not just before the fix. That first look is where the symptom gets patched and the cause survives. It applies even when the report is thin ("this stack trace", "the deploy fails") and even when the next step seems obvious: gathering what is missing is the skill's own first step. Triggers on "fix it", "patch it", "find out why", "get to the bottom of it", « ce test est flaky, corrige-le », « ça marchait avant, maintenant ça plante ». Not for new code, features, error handling, refactoring code that works, CI/tooling setup, or reviewing code that already works.
phmatray/ai-migration-kit · ★ 3 · Code & Development · score 75

Install: claude install-skill phmatray/ai-migration-kit

# Debug an issue — the root cause before any fix ## Overview When something breaks, the fastest-feeling move is to change the line where the error appears and re-run. That instinct is usually wrong: it fixes where the problem *surfaces*, not where it *starts*. The symptom goes quiet, the cause stays, and it resurfaces later — often somewhere harder to see. **Core principle:** Find the root cause before changing code. A fix you can't explain is a guess, and guesses tend to add new variables rather than remove the broken one. This skill is a process for not-guessing. It is most valuable exactly when guessing is most tempting — under time pressure, when a quick patch looks obvious, or after a fix has already failed. ## The Iron Law ``` NO FIX WITHOUT A ROOT CAUSE YOU CAN EXPLAIN ``` If you cannot say *"this fails because X, and here is the evidence,"* you are not ready to propose a fix. Finish Phase 1 first. This isn't bureaucracy — it's the one rule that separates debugging from thrashing. Every shortcut around it trades a few minutes now for a latent bug and a longer second session later. ## When to use Use for any technical issue: failing tests, production bugs, unexpected behavior, performance problems, build failures, integration issues, flaky tests. The process matters **most** in the moments it feels least affordable: - **Under time pressure** — an outage or a deadline makes guessing feel responsible. It isn't; a wrong guess extends the outage and you still ha