debugging
Installation
SKILL.md
Debugging
Purpose
Find the confirmed root cause of a local development failure, fix it, and preserve a regression check without confusing symptoms for causes.
Workflow
- Capture the exact symptom, command, inputs, environment, recent changes, and expected behavior. Treat a user-reported failure and supplied evidence as ground truth; do not require rerunning it.
- Build a tight red-capable feedback loop before theorizing when reproduction execution is explicitly authorized and runnable. If no authorized or runnable loop exists, preserve supplied trace/source evidence and label causal statements as hypotheses; do not claim confirmation or a fix.
- Read stack traces bottom-up, separate triggering symptoms from causal evidence, and form ranked hypotheses. Static source/trace reasoning MAY produce a useful hypothesis without a loop, but MUST state the missing experiment and prediction.
- Isolate one variable at a time and bisect when the search space supports it. Tag temporary debug logs uniquely and remove them before completion.
- Confirm a root cause only with a falsifiable experiment; correlation, static plausibility, and a passing unrelated check are insufficient.
- Apply the narrowest maintainable fix only after appropriate evidence. Verify against the original repro and nearby behavior only when explicitly authorized.
- Add a regression check that fails before the fix and passes after it when execution is authorized; otherwise record the missing seam.
- Stop and escalate when required state, ownership, or safe evidence is unavailable, preserving artifacts and the next owner/action.