# Debugging Systematically

> Investigates and fixes a bug, error, or unexpected behavior methodically instead of guessing. Use whenever the task is "this is broken" or "X isn't working" rather than building something new.

- Skill: `aaravriyer193/debugging-systematically` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aaravriyer193/debugging-systematically`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aaravriyer193/debugging-systematically/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: aaravriyer193 (https://skillmd.com/u/aaravriyer193)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/aaravriyer193/debugging-systematically

---


# Debugging systematically

Don't guess-and-check by editing code and hoping. Work the actual chain of evidence:

1. **Reproduce it.** Run the exact failing command/action before touching anything — confirm the same failure, not a different one.
2. **Read the real error**, not the symptom. A stack trace or exit code tells you where, not always why — but it's still the starting point.
3. **Narrow the cause.** Check logs (`shell` to tail/grep them), add a temporary print/log if the failure point isn't obvious, or bisect (isolate half the suspect code) rather than reading the whole codebase hoping to spot it.
4. **Form a specific hypothesis** before changing code — "X is null because Y never sets it," not "let me try changing this and see."
5. **Fix the root cause**, not the symptom — a null check that hides a bug is worse than fixing why it's null, unless null is actually a valid, expected state.
6. **Verify the fix** by re-running the exact repro from step 1, not just "it looks right now."

If a fix doesn't hold up on verification, don't layer another patch on top — go back to step 3. Two unexplained fixes stacked on each other usually means the real cause hasn't been found yet.