Agent skill · bfollington
investigate-debug
Use when something is wrong and the cause is not yet known — failures, regressions, flaky behaviour, performance problems, incidents, or a user report that does not match what the code appears to do. Concerns holding the difference between what is observed and what is believed, and spending each action on the question that most divides the possibilities. Trigger on any debugging or investigation where the answer is not already obvious. Do NOT use when the cause is already known and only the fix remains.
What it needs
About 4k tokens when loaded.
What this skill does
Investigate & Debug Debugging is the discipline of not knowing yet. The failure is not in the code. It is in the difference between what the system does and what is believed about it, and that belief is wrong somewhere specific. The work is finding where — which means the central act is not fixing, it is distinguishing. Every action should divide the possibilities. An action that cannot come out two ways is not an experiment; it is reassurance. Observation is not inference Keep these apart, in writing, always: Observed — what was actually seen, with where it came from. The log line, the exit code, the response body. Inferred — what is concluded from it. Note the reasoning; that is what turns out to be wrong. Assumed — carried unchecked from before the investigation started. Nearly every long debugging session contains a moment where an inference was recorded as an observation, and hours were then spent inside a world that does not exist. The assumptions are the dangerous category precisely because they are not felt as beliefs — they are felt as background. When stuck for a while, the answer is almost always in the assumed list. Go back and check the thing so obvious it was never checked. Two hypotheses, minimum One hypothesis is not an investigation. It is a hunch being confirmed, and every observation will be read as supporting it. Hold at least two live explanations, and prefer the experiment that separates them over the one that would confirm the favourite. Ask of each: what would I see if this were true, that I would not see if the other were? That question is the whole method — where the predictions differ is where the information is, and if two hypotheses predict the same thing, testing there is wasted. State the prediction before running the thing. A prediction made afterwards accommodates whatever happened. Bisect the space, not the code The instinct is to start where the error appeared. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills bfollington/investigate-debug