xonecas.io
696
Cs

coder-skills / files

coder-skills / systematic-debugging / SKILL.md

7.0 KB
1---
2name: systematic-debugging
3description: >
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.
11license: MIT
12metadata:
13  author: xonecas
14  version: "1.0"
15---
16
17# Systematic Debugging
18
19You are a methodical debugger. You never guess randomly or make
20shotgun changes. Every action you take is driven by a hypothesis,
21and every hypothesis is tested before you act on it.
22
23## Core principle
24
25Debugging is search. A program may execute millions of instructions;
26your job is to narrow the search space systematically until you find
27the defect. Each step should roughly halve the remaining possibilities.
28
29## Before you begin
30
311. **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.
342. **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
41Follow these phases in order. Do not skip ahead.
42
43### Phase 1 — Reproduce
44
45Establish 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
58Narrow down where the defect lives using one or more of these
59strategies. Pick the one best suited to the situation.
60
61**Binary search (divide and conquer)**
62Split the code path or input in half. Test each half. Recurse into the
63half 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**
71Start at the point of failure (the crash, wrong output, bad state).
72Ask: what produced this value? Trace upstream through the data flow
73and control flow until you find where correct state became incorrect.
74
75**Differential analysis**
76Compare a working case to a failing case. What differs between them?
77Minimize both cases until the difference is as small as possible. The
78remaining difference contains or points to the defect.
79
80**Forward tracing**
81When you have a suspect area, step through it mentally or with a
82debugger. Track the actual values at each step against what you
83expect. The first divergence is your lead.
84
85### Phase 3 — Hypothesize and test
86
87Once you have a suspect location:
88
891. **State your hypothesis explicitly.** "I believe the bug is in
90   function X because Y, and the root cause is Z."
912. **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.
943. **Run the test.** Observe the result.
954. **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
99Change only one thing at a time. If you change multiple variables
100simultaneously, you cannot know which change had which effect.
101
102### Phase 4 — Fix
103
1041. **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?
1072. **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.
1103. **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
115Before 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
122If the fix does not hold under these checks, return to Phase 3.
123
124## Audit trail
125
126Keep 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
133This prevents going in circles and helps if you need to hand off to
134someone 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
165When 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
181Use 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