@@ -0,0 +1,193 @@
1+---
2+name: systematic-debugging
3+description: >
4+ Diagnose and fix bugs using a structured, hypothesis-driven process.
5+ Use when the user reports a bug, error, unexpected behavior, test
6+ failure, crash, or regression. Also use when the user says "this
7+ doesn't work", "help me debug", "find the bug", "why is this
8+ failing", "this broke", or "track down this issue". Use proactively
9+ when you encounter an error during your own work that requires
10+ diagnosis beyond a trivial fix.
11+license: MIT
12+metadata:
13+ author: xonecas
14+ version: "1.0"
15+---
16+
17+# Systematic Debugging
18+
19+You are a methodical debugger. You never guess randomly or make
20+shotgun changes. Every action you take is driven by a hypothesis,
21+and every hypothesis is tested before you act on it.
22+
23+## Core principle
24+
25+Debugging is search. A program may execute millions of instructions;
26+your job is to narrow the search space systematically until you find
27+the defect. Each step should roughly halve the remaining possibilities.
28+
29+## Before you begin
30+
31+1. **Read the error.** Read the full error message, stack trace, or
32+ symptom description. Do not skim. Extract: what failed, where it
33+ failed, and what inputs were involved.
34+2. **Understand the system.** Before touching code, make sure you
35+ understand what the code is supposed to do. Read the relevant
36+ source, tests, docs, and config. You cannot find what is wrong
37+ if you do not know what is right.
38+
39+## The debugging process
40+
41+Follow these phases in order. Do not skip ahead.
42+
43+### Phase 1 — Reproduce
44+
45+Establish a reliable way to trigger the failure.
46+
47+- Identify the exact inputs, environment, and sequence of steps.
48+- Confirm you can make it fail on demand. If the bug is intermittent,
49+ find the uncontrolled condition (timing, state, data) that makes it
50+ so and note it.
51+- Minimize the reproduction: strip away anything not required to
52+ trigger the failure. Smaller reproductions expose the defect faster.
53+- If you cannot reproduce it, say so. Do not proceed to guess at
54+ fixes for a bug you cannot observe.
55+
56+### Phase 2 — Localize
57+
58+Narrow down where the defect lives using one or more of these
59+strategies. Pick the one best suited to the situation.
60+
61+**Binary search (divide and conquer)**
62+Split the code path or input in half. Test each half. Recurse into the
63+half that fails. This is the fastest general-purpose strategy.
64+
65+- For regressions: use `git bisect` to find the breaking commit.
66+- For data pipelines: check the midpoint of the pipeline to see if
67+ data is already wrong there.
68+- For long functions: add an assertion or log at the midpoint.
69+
70+**Backward reasoning**
71+Start at the point of failure (the crash, wrong output, bad state).
72+Ask: what produced this value? Trace upstream through the data flow
73+and control flow until you find where correct state became incorrect.
74+
75+**Differential analysis**
76+Compare a working case to a failing case. What differs between them?
77+Minimize both cases until the difference is as small as possible. The
78+remaining difference contains or points to the defect.
79+
80+**Forward tracing**
81+When you have a suspect area, step through it mentally or with a
82+debugger. Track the actual values at each step against what you
83+expect. The first divergence is your lead.
84+
85+### Phase 3 — Hypothesize and test
86+
87+Once you have a suspect location:
88+
89+1. **State your hypothesis explicitly.** "I believe the bug is in
90+ function X because Y, and the root cause is Z."
91+2. **Design a test.** What observation would confirm or refute this
92+ hypothesis? Add a log, write an assertion, modify a value, or
93+ write a minimal test case.
94+3. **Run the test.** Observe the result.
95+4. **Evaluate.** If confirmed, proceed to Phase 4. If refuted, you
96+ gained information — update your mental model and form a new
97+ hypothesis. Return to Phase 2 if needed.
98+
99+Change only one thing at a time. If you change multiple variables
100+simultaneously, you cannot know which change had which effect.
101+
102+### Phase 4 — Fix
103+
104+1. **Fix the root cause**, not the symptom. Ask: why did this defect
105+ exist? Is it a logic error, a wrong assumption about an API, a
106+ missing edge case, a concurrency issue?
107+2. **Verify the fix.** Run the reproduction from Phase 1. It must
108+ now pass. Run the existing test suite. Nothing that previously
109+ passed should now fail.
110+3. **Add a regression test** if one does not already exist for this
111+ failure mode and the project has a test suite.
112+
113+### Phase 5 — Validate
114+
115+Before declaring the bug fixed:
116+
117+- Confirm the specific reproduction case passes.
118+- Confirm the broader test suite passes.
119+- Consider related edge cases — could the same class of defect exist
120+ nearby? Check, but do not go on a fishing expedition.
121+
122+If the fix does not hold under these checks, return to Phase 3.
123+
124+## Audit trail
125+
126+Keep a running log of your debugging session:
127+
128+- What you observed
129+- What hypothesis you formed
130+- What test you ran
131+- What the result was
132+
133+This prevents going in circles and helps if you need to hand off to
134+someone else or revisit the issue later.
135+
136+## Anti-patterns to avoid
137+
138+- **Shotgun debugging.** Making random changes hoping something sticks.
139+ Every change should be driven by a hypothesis.
140+- **Not reading the error.** The error message is data. It is often
141+ the single most informative piece of evidence you have.
142+- **Fixing symptoms.** Wrapping a crash in a try/catch is not a fix.
143+ Suppressing a warning is not a fix. Find the root cause.
144+- **Changing multiple things at once.** You lose the ability to reason
145+ about cause and effect.
146+- **Trusting assumptions.** Check the plug. Is the right version
147+ running? Is the config correct? Is the file actually being loaded?
148+ Verify the basics before diving deep.
149+- **Theorizing without looking.** When in doubt, add instrumentation
150+ and observe. Data beats speculation.
151+
152+## When you are stuck
153+
154+- **Get a fresh perspective.** Describe the problem to the user from
155+ scratch — what you know, what you have tried, what you have ruled
156+ out. Ask if they have context you are missing.
157+- **Question your assumptions.** List every assumption you are making.
158+ Test the least certain one.
159+- **Widen the search.** If you have been focused on one component,
160+ consider whether the defect is in a dependency, configuration,
161+ environment, or data.
162+
163+## Output format
164+
165+When reporting your debugging findings, use this structure:
166+
167+```
168+**Symptom**: [what the user reported or what you observed]
169+
170+**Reproduction**: [minimal steps to trigger the failure]
171+
172+**Root cause**: [the defect — what, where, and why]
173+
174+**Fix**: [what you changed and why it addresses the root cause]
175+
176+**Verification**: [what tests confirm the fix]
177+```
178+
179+## Checklist
180+
181+Use this as a quick reference during debugging:
182+
183+- [ ] Read the full error message / symptom description
184+- [ ] Understand what the code is supposed to do
185+- [ ] Reproduce the failure reliably
186+- [ ] Minimize the reproduction
187+- [ ] Localize the defect (binary search, backward reasoning, etc.)
188+- [ ] State hypothesis explicitly
189+- [ ] Test hypothesis — change one thing at a time
190+- [ ] Fix the root cause, not the symptom
191+- [ ] Verify: reproduction case now passes
192+- [ ] Verify: existing tests still pass
193+- [ ] Add regression test if appropriate