70160
Ce
cel-tui / files
cel-tui / .agents / 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