What is Debugging Expert?

A systematic troubleshooting skill that uses the Scientific Method to identify and fix root causes rather than guessing.

How should I run experiments?

Create a reproducible case and change one variable at a time to validate the hypothesis.

How do I know the issue is fixed?

Verify the fix works and run checks to ensure no regressions were introduced.

Debugging Expert

Scanned

npx machina-cli add skill hoangnguyen0403/agent-skills-standard/debugging --openclaw

Files (1)

SKILL.md

1.6 KB

Debugging Expert

Priority: P1 (OPERATIONAL)

Systematic, evidence-based troubleshooting. Do not guess; prove.

🔬 The Scientific Method

OBSERVE: Gather data. What exactly is happening?
- Logs, Stack Traces, Screenshots, Steps to Reproduce.
HYPOTHESIZE: Formulate a theory. "I think X is causing Y because Z."
EXPERIMENT: Test the theory.
- Create a reproduction case.
- Change one variable at a time to validate the hypothesis.
FIX: Implement the solution once the root cause is proven.
VERIFY: Ensure the fix works and doesn't introduce regressions.

🚫 Anti-Patterns

Shotgun Debugging: Randomly changing things hoping it works.
Console Log Spam: Leaving print/console.log in production code.
Fixing Symptoms: masking the error (e.g., try-catch without handling) instead of fixing the root cause.

🛠 Best Practices

Diff Diagnosis: What changed since it last worked?
Minimal Repro: Create the smallest possible code snippet that reproduces the issue.
Rubber Ducking: Explain the code line-by-line to an inanimate object (or the agent).
Binary Search: Comment out half the code to isolate the failing section.

📚 References

Bug Report Template

Source

git clone https://github.com/hoangnguyen0403/agent-skills-standard/blob/develop/.github/skills/common/debugging/SKILL.mdView on GitHub

Overview

Debugging Expert applies the Scientific Method to troubleshoot issues without guessing. It emphasizes observable data, forming testable hypotheses, controlled experiments, and a verified fix to prevent regressions.

How This Skill Works

Observe data (logs, stack traces, steps to reproduce) to identify what happened. Hypothesize a predicated cause, then design controlled experiments by changing one variable at a time and creating a reproduction case. Implement the fix once the root cause is proven, then verify that the fix works and does not introduce regressions.

When to Use It

When an error is reproducible but the root cause is unclear.
When symptoms do not match logs or expected behavior.
During post-incident reviews to isolate root cause.
Before deploying code to production to prevent regressions.
When debugging across a large codebase with multiple failure points.

Quick Start

Step 1: Observe and collect data from logs, traces, errors, and steps to reproduce.
Step 2: Hypothesize a root cause and design controlled experiments that change one variable at a time.
Step 3: Implement the fix and verify the issue is resolved without introducing new problems.

Best Practices

Diff Diagnosis: identify what changed since it last worked.
Minimal Repro: create the smallest possible snippet that reproduces the issue.
Rubber Ducking: explain the code line by line to an inanimate object or the agent.
Binary Search: narrow down the failing section by halving the suspect area.
One-variable-at-a-time experiments: change a single factor to validate the hypothesis.

Example Use Cases

Crashing microservice diagnosed by logs and a reproduction case to prove the root cause.
Intermittent UI bug isolated by running controlled experiments across states.
Flaky tests reproduced with a minimal repro and binary search to pinpoint the failure.
API returning stale data traced to incorrect parsing after a schema change.
Memory leak fixed after diffing changes and verifying no regressions.

Frequently Asked Questions

Add this skill to your agents