| name | diagnosing-bugs |
| description | Diagnose a reported bug, a failing CI or lint job, or a performance regression, and find its cause. Use when something is broken, failing, throwing, hanging, or slower than it was, when CI or a pipeline fails, or when the user asks why something is happening. |
| argument-hint | [<what is broken>] |
Diagnosing Bugs
Diagnose the failure in $ARGUMENTS, or the one the user just reported.
Reproduce
Build one command that fails on this bug. Reading and grepping to work out how to invoke the failing path is how you build it, not a detour around it.
A command that shows only that nothing crashed does not count. It has to drive the real code path and produce the symptom that was reported.
For a failing CI or pipeline job, that command already ran. Use github:actions-monitor or gitlab:ci-monitor to get the logs rather than reconstructing the job locally.
When nothing you try reaches the bug, say so and stop. Name what you tried and what each attempt could not reach, then ask for an environment where it reproduces, a captured artifact, or permission to add instrumentation.
Find the Cause
Change one thing per run and let the command settle it. A cause the command has not responded to is a guess, and saying which line is at fault is not the same as showing the command go green when you change it.
Report one cause. When the cause is not clear, say what you ruled out and how you ruled it out, then ask rather than presenting a list to choose from.
Hand Off
With the cause established and the fix clear, enter plan mode and map out the implementation.
When the user asked you to diagnose without changing anything, stop at the cause and the plan.
Confirm
Once a fix is in, run the original reproduction again. Report it fixed only after that command passes, and quote the run.
A fix that was never run against the thing that failed is not a fix, and neither is one verified against a smaller case you built along the way.
