rikilamadrid Debug Issue
Debug an observed failure by reducing uncertainty before changing code.
The goal is not to try fixes until something works.
The goal is to explain the failure well enough that the smallest correct fix becomes justified.
Reproduce before repairing.
When to use
Use Debug Issue when there is a concrete unexpected behavior such as:
- a failing test
- runtime error
- broken feature
- regression
- incorrect output
- integration failure
- environment-specific failure
- intermittent behavior that needs isolation
- production or staging behavior that differs from expectation
Do not use it merely because implementation work is difficult.
If the task is planned construction, use /ticket start.
If the goal is reviewing completed implementation for possible defects, use /ticket review.
If the real question is broad understanding of the repository, use learn-codebase.
Goal
Answer:
What is failing, why is it failing, and what evidence proves the explanation?
Then apply the smallest justified correction and verify the original failure no longer occurs.
1. Establish the failure
Before proposing a fix, define:
- expected behavior
- actual behavior
- where the failure occurs
- how it was observed
- whether it is reproducible
- relevant environment or conditions
- known recent changes when relevant
Prefer the smallest reliable reproduction.
If the failure cannot be reproduced, preserve the available evidence and state that limitation explicitly.
Do not manufacture certainty.
2. Inspect before changing
Read only the code, logs, tests, configuration, dependencies, and context relevant to the failure.
Identify the execution path involved.
Do not begin with broad refactoring.
Do not change unrelated code while still determining the cause.
3. Form hypotheses
Produce a small ranked set of plausible explanations.
For each hypothesis state:
- why it fits the evidence
- what evidence would support it
- what evidence would disprove it
- the cheapest useful test
Prefer hypotheses that explain all known symptoms rather than only one.
Do not create a long speculative list.
4. Test discriminating evidence
Test the cheapest hypothesis that meaningfully reduces uncertainty.
Change one explanatory variable at a time when practical.
Examples:
- inspect a value at the failure boundary
- run one targeted test
- compare working and failing environments
- trace one request
- check one dependency or configuration assumption
- temporarily instrument the relevant path
- isolate one integration
A debugging action should answer a question.
Avoid random edits intended only to "see if it works."
5. Identify the root cause
Do not call something the root cause merely because changing it makes the symptom disappear.
A root-cause claim should explain:
- why the failure occurred
- why it occurred under the observed conditions
- why the evidence supports this explanation
- why competing explanations are less likely
If the evidence only supports a workaround or probable cause, say so.
6. Choose the smallest justified fix
Once the cause is sufficiently established:
- fix the cause rather than only the visible symptom when practical
- preserve existing behavior outside the failure
- avoid unrelated cleanup
- avoid dependency, architecture, schema, security, or workflow changes without required approval
- prefer a focused regression test when appropriate
If the correct fix expands beyond the active feature or approval boundary, stop and explain the decision required.
7. Verify
Verification must include the original failure.
Where relevant also verify:
- the reproduction now passes
- nearby behavior still works
- regression tests pass
- edge/failure states remain correct
- temporary instrumentation is removed
- no unrelated behavior changed
Do not declare success only because the code compiles or one unrelated test passes.
8. Stop conditions
Stop and report rather than thrashing when:
- 2–3 grounded hypotheses have been tested without reducing uncertainty
- necessary evidence or environment access is unavailable
- reproduction is too unstable to support a safe fix
- the likely fix requires an unapproved architectural, dependency, security, data, or destructive change
- the observed behavior conflicts with documented requirements and a human decision is needed
When stopping, preserve what has been ruled out so the next attempt does not restart from zero.
Output
Return:
Failure
Expected vs actual behavior and reproduction status.
Evidence
The relevant observations, logs, tests, or code paths.
Hypotheses tested
What was tested and what each result ruled in or out.
Root cause
The established cause, probable cause, or remaining uncertainty.
Fix
The smallest change made or recommended.
Verification
How the original failure and relevant regression surface were checked.
Residual risk
Anything still uncertain or unverified.
Handoff
If unresolved, state the exact next useful investigation step and what should not be repeated.
Boundaries
debug-issue diagnoses an observed failure.
It does not:
- implement unrelated feature scope
- perform a general repository review
- replace
/ticket review - replace
/ticket complete - silently change architecture or dependencies
- turn debugging into opportunistic refactoring
- hide uncertainty behind a successful-looking workaround
Principles
Reproduce before repairing.
A debugging action should answer a question.
Change one explanatory variable at a time.
Fixes follow evidence, not guesses.
A symptom disappearing is not proof of root cause.
Preserve what has already been ruled out.
Stop when additional attempts are producing activity instead of information.