copy paste

skills/debugging/debugging-workflow.md

@@ -0,0 +1,46 @@
+# Debugging Workflow
+
+## Purpose
+
+Find root cause efficiently and verify fixes with a disciplined workflow that avoids premature assumptions and shallow symptom treatment.
+
+## When to use
+
+- The defect is real but the cause is unclear
+- A failing test needs investigation
+- The system has inconsistent or environment-specific behavior
+- A regression may have multiple plausible causes
+
+## Inputs to gather
+
+- Reproduction path or failing signal
+- Relevant code paths, logs, traces, state transitions, and recent changes
+- Existing tests or ways to validate a hypothesis
+- Environment details that may influence behavior
+
+## How to work
+
+- Reproduce first when possible, then narrow scope by isolating the smallest failing path.
+- Form hypotheses from evidence, not instinct alone, and invalidate them aggressively.
+- Inspect boundaries: inputs, outputs, state mutations, async timing, external dependencies, and configuration.
+- Fix the root cause rather than only masking symptoms when feasible.
+- Re-run the original failing signal and add regression protection if appropriate.
+
+## Output expectations
+
+- Root cause explanation tied to evidence
+- Fix or recommended fix approach
+- Verification that the original issue is resolved
+- Remaining uncertainty, if any
+
+## Quality checklist
+
+- The explanation connects cause to symptom clearly.
+- The chosen fix addresses the real failure mechanism.
+- Verification includes the original failing path.
+- Regression protection is considered when the bug is likely to recur.
+
+## Handoff notes
+
+- Note whether the issue was fully reproduced, partially inferred, or fixed based on a probable cause.
+- Mention monitoring or follow-up checks if confidence is limited by environment or observability.