common-debugging git:20260714.6bf9b5eA

Immutable. This exact content is served forever at /api/v1/blob/9701906d15c35214.

---
name: common-debugging
description: Troubleshoot systematically using the Scientific Method. Use when debugging crashes, tracing errors, diagnosing unexpected behavior, or investigating exceptions.
metadata:
  triggers:
    keywords:
    - debug
    - fix bug
    - crash
    - error
    - exception
    - troubleshooting
---
# Debugging Expert

## **Priority: P1 (HIGH)**

## Root-Cause Protocol

1. **OBSERVE**: Gather error, logs, repro steps, recent diffs.
2. **REPRODUCE**: Make the failure happen on demand or gather more evidence.
3. **HYPOTHESIZE**: State one hypothesis in plain language.
4. **EXPERIMENT**: Change one variable to prove or kill the theory.
5. **FIX**: Touch code only after root cause proven.
6. **VERIFY**: Re-run the failing case and regression checks.

## Red Flags

- **Stop if you are changing code before repro**: You are guessing.
- **Stop if fix #2 starts before understanding fix #1**: Re-open root cause.
- **Stop if "quick patch for now" appears**: Symptom masking starts there.

## Rationalization Prevention

- **"The bug is obvious"**: Obvious bugs still need evidence.
- **"I already tried a few things"**: That means you need structure.
- **"It only fails in prod"**: Gather prod evidence, do not invent local myths.
- **Minimal repro first**: A minimal reproduction beats more random fixes.

## Anti-Patterns

- **No shotgun debugging**: Prove root cause before changing code.
- **No debug prints in production**: Remove all print/console.log before commit.
- **No symptom masking**: Fix root cause; never swallow errors without handling.

## References

- [Bug Report Template](references/bug-report-template.md)

## Incident pressure checklist

- For production incidents, reproduce with a production-like replay and state one hypothesis before changing code; stop symptom patches until the root cause is proven.

## Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:
- hypothesis
- one hypothesis
- stop

- Additional task-grounded exact anchors: minimal