Menü
Real-engineer debugging loop — reproduce, minimise, hypothesise, instrument, fix, regression-test. Use when the user reports "X is broken", "this used to work", "I'm getting error Y", or any unexplained failure. Replaces shotgun-debugging with a disciplined cycle.
| name | diagnose |
| description | Real-engineer debugging loop — reproduce, minimise, hypothesise, instrument, fix, regression-test. Use when the user reports "X is broken", "this used to work", "I'm getting error Y", or any unexplained failure. Replaces shotgun-debugging with a disciplined cycle. |
| license | MIT |
| metadata | {"author":"yottacode","inspired-by":"https://github.com/mattpocock/skills"} |
Bugs are explanations of the gap between the model in your head and the behavior of the system. Closing the gap goes through six steps, in order. Skipping a step almost always means the fix is in the wrong place.
Before changing anything, get the failure to happen on demand. A bug you can't reproduce is a bug you can't verify you fixed.
for i in {1..50}; do ...; done) and record the failure rate.If you cannot reproduce in this session, stop and ask the user for the missing input. Do not "fix" code that you can't prove is broken.
Strip away everything that isn't necessary to trigger the failure. The smaller the reproducer, the smaller the hypothesis space.
curl, not the framework that wraps it.The endpoint is a reproducer you could paste into an issue. If you can't fit it in 30 lines, keep cutting.
State out loud what you think is happening, and what would prove or disprove it.
Pick one hypothesis at a time. Two changes at once = no signal.
When the hypothesis isn't directly observable, add an observation. Don't guess.
| Question | Instrument |
|---|---|
| "What is this variable at line N?" | Log it. Or dlv / gdb / a debugger if local. |
| "Which code path runs?" | Log on entry to each branch. |
| "Why is the response slow?" | Time each step; sum to the total. |
| "Where does the data get corrupted?" | Log the value before and after each transformer. |
| "Did this function get called at all?" | Log on entry. |
Print statements are not unprofessional. They are the fastest path to a confirmed hypothesis. Remove them after the fix lands.
Once you have a confirmed root cause, apply the minimum change that addresses it.
If the fix would be much bigger than the bug, stop and reconsider — you might be confusing a symptom for the cause.
Every bug fix ships with a test that fails on the broken version and passes on the fixed version.
Stop and ask the user when:
Sketch the smallest viable next step rather than implementing a sweeping change without alignment.
Pre-plan design interview. Use when the user asks for a feature or change and the right shape isn't obvious yet — before writing-plans, before code. Surfaces requirements, constraints, and trade-offs so the eventual plan rests on a real spec.
Capture the *why* behind decisions as you ship — ADRs for choices that are expensive to reverse, why-comments for non-obvious code, and rules files that stay current. Use when making an architectural decision, changing a public API, or when you've had to explain the same thing twice.
Review a Dockerfile (or Containerfile) for correctness, layer caching, multi-stage opportunities, image size, security, and reproducibility. Use when the user asks "review my Dockerfile", "why is my image so large?", or "is this Dockerfile good?".
Execute an approved plan step-by-step with checkpoints, batched edits, and visible progress. Use when a plan has been approved and you're about to start implementing, or when the user says "go ahead with the plan", "implement it", or hands you a checklist of steps.
Use `git log`, `git blame`, and `git bisect` to track down when a regression was introduced or why a line of code looks the way it does. Use when the user asks "when did X break?", "who wrote this?", "find the commit that introduced Y", or any historical inquiry about the codebase.
Generate a concise handoff document that a fresh agent (or the same agent in a new session) can use to pick up where the current one left off. Use when the user asks to "summarize where we are", "make a handoff", "compact context before /clear", or any session-transition request.