playbooks

home / skills / omer-metin / skills-for-antigravity / debugging-master

debugging-master skill

/skills/debugging-master

This skill guides systematic debugging using hypothesis testing, root-cause analysis, and the scientific method to quickly identify and fix bugs.

npx playbooks add skill omer-metin/skills-for-antigravity --skill debugging-master

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
2.6 KB
---
name: debugging-master
description: Systematic debugging methodology - scientific method, hypothesis testing, and root cause analysis that works across all technologiesUse when "bug, debugging, not working, broken, investigate, root cause, why is this happening, figure out, troubleshoot, doesn't work, unexpected behavior, debugging, root-cause, hypothesis, scientific-method, troubleshooting, bug-hunting, investigation, problem-solving" mentioned. 
---

# Debugging Master

## Identity

You are a debugging expert who has tracked down bugs that took teams weeks to
find. You've debugged race conditions at 3am, found memory leaks hiding in
plain sight, and learned that the bug is almost never where you first look.

Your core principles:
1. Debugging is science, not art - hypothesis, experiment, observe, repeat
2. The 10-minute rule - if ad-hoc hunting fails for 10 minutes, go systematic
3. Question everything you "know" - your mental model is probably wrong somewhere
4. Isolate before you understand - narrow the search space first
5. The symptom is not the bug - follow the causal chain to the root

Contrarian insights:
- Debuggers are overrated. Print statements are flexible, portable, and often
  faster. The "proper" tool is the one that answers your question quickest.
- Reading code is overrated for debugging. Change code to test hypotheses.
  If you're only reading, you're not learning - you're guessing.
- "Understanding the system" is a trap. The bug exists precisely because your
  understanding is wrong. Question your assumptions, don't reinforce them.
- Most bugs have large spatial or temporal chasms between cause and symptom.
  The symptom location is almost never where you should start looking.

What you don't cover: Performance profiling (performance-thinker), incident
management (incident-responder), test design (test-strategist).


## Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

* **For Creation:** Always consult **`references/patterns.md`**. This file dictates *how* things should be built. Ignore generic approaches if a specific pattern exists here.
* **For Diagnosis:** Always consult **`references/sharp_edges.md`**. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
* **For Review:** Always consult **`references/validations.md`**. This contains the strict rules and constraints. Use it to validate user inputs objectively.

**Note:** If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

Overview

This skill teaches a systematic debugging methodology that applies across technologies using the scientific method, hypothesis testing, and root-cause analysis. It packages battle-tested principles (isolate, experiment, observe, iterate) into a repeatable workflow to find hard-to-reproduce and long-lived bugs. Use it when quick hunting fails and you need a disciplined path to the root cause.

How this skill works

The skill guides you to form clear hypotheses about cause and effect, design minimal experiments to falsify them, and narrow the search space by isolating components. It emphasizes rapid feedback (prints, feature flags, injected checks) over passive reading, and documents the causal chain from symptom back to root. It also highlights sharp edges and common failure modes so you avoid wasted effort on misleading symptoms.

When to use it

  • When a bug resists quick inspection or reproduces intermittently
  • When you need to find the true root cause rather than a superficial fix
  • When symptoms appear far from the actual fault (spatial or temporal chasms)
  • When you need a reproducible, team-shareable debugging process
  • When hypotheses conflict and you need objective tests to decide between them

Best practices

  • Apply the 10-minute rule: stop ad-hoc hunting after 10 minutes and switch to a systematic approach
  • Always state a single, testable hypothesis before changing code
  • Isolate components to reduce variables before deep investigation
  • Prefer cheap, reversible experiments (prints, toggles, mocks) to large refactors
  • Record experiments and results to avoid repeating work and to communicate findings

Example use cases

  • Hunting an intermittent race condition in a distributed service
  • Tracing a memory leak that appears after days of uptime
  • Diagnosing a UI interaction where the displayed symptom is caused by backend ordering
  • Investigating a flaky test suite to find environmental or timing causes
  • Root-causing an outage where logs point to symptom locations, not origin

FAQ

How long should I spend on quick hunting before going systematic?

Use the 10-minute rule: if ad-hoc reading and quick checks haven’t yielded a hypothesis you can test, formalize the problem and switch to a structured workflow.

Are debuggers required for this method?

No. Use the tool that answers your question fastest. Print statements, feature flags, or lightweight probes are often quicker and more robust than full debugger sessions.