{"id":53880,"plugin_id":"plugins_6ac84bac80b081918c305a1574fbd186","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-24T13:55:15.378Z","digest":"6bb1c7e50d42aff09954ebf2800e4bbd26b1ae3ce2471326393c4d8bf4073cbd","against":null,"payload":{"description":"Finds the root cause of a bug, test failure, or unexpected behavior before proposing any fix. Use this whenever something is broken and the cause is not yet proven — a failing test, a production error, intermittent behavior, or a symptom that appeared after a change. Also use when a fix has been attempted and did not work, or when the same bug keeps coming back.","included_files":[],"name":"systematic-debugging","skill_md_contents":"---\nname: systematic-debugging\ndescription: Finds the root cause of a bug, test failure, or unexpected behavior before proposing any fix. Use this whenever something is broken and the cause is not yet proven — a failing test, a production error, intermittent behavior, or a symptom that appeared after a change. Also use when a fix has been attempted and did not work, or when the same bug keeps coming back.\n---\n\n# Systematic debugging\n\n## The rule\n\n**No fix before the cause is proven.** A change that makes a symptom disappear without an\nexplanation has not fixed anything — it has moved the failure somewhere you are not looking.\n\n## Method\n\n1. **Reproduce it deterministically.** If you cannot make it happen on demand, you cannot know when\n   it is fixed. Intermittent means you have not found the variable yet — order, timing, state,\n   environment, data.\n2. **Narrow the blast radius.** Bisect: which commit, which input, which branch, which layer. Halve\n   the search space with each step rather than reading everything.\n3. **State a hypothesis that can be wrong.** \"The cache returns stale rows after a write\" is a\n   hypothesis. \"Something is wrong with caching\" is not.\n4. **Test the hypothesis directly** — a log line, a breakpoint, a probe. Prove it, do not infer it.\n5. **Explain the whole symptom.** If your cause explains the error but not why it started Tuesday,\n   you have found *a* bug, not *the* bug.\n6. **Fix, then verify by reverting.** Put the bug back and confirm the test fails again. This is the\n   step people skip, and it is the one that proves causation rather than coincidence.\n\n## Anti-patterns\n\n- **Shotgun changes** — altering several things at once. Now you cannot attribute the fix.\n- **\"Probably a flake.\"** Not a diagnosis. A test that fails intermittently is reporting a real\n  race, ordering dependency, or shared-state leak.\n- **Fixing the symptom** — catching the exception, adding a retry, widening a timeout — without\n  knowing what threw it.\n- **Trusting the error message's location.** Where it surfaced is rarely where it originated.\n\n## Never\n\n- Close a bug without a reproduction that failed before the fix and passes after it.\n- Deploy a change to production to find out whether it works. Reproduce somewhere you can observe first.\n- Change the environment and the code in the same step.\n- Leave a debugging aid in the code as the fix — a widened timeout, a disabled check, a swallowed exception.\n\n## Return contract\n\nState the reproduction, the proven cause, the fix, and the verification that the fix addresses that\ncause specifically. Name anything you ruled out and how.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}