Describe the observed failure
Write what you expected, what actually happened and the smallest known input that triggers the difference. Include the relevant environment without exposing credentials or personal data. A message such as it does not work gives little guidance. Distinguish a crash from an incorrect output or a misunderstanding of the specification. You cannot evaluate a fix until you know which behaviour the program was supposed to produce.
Build a minimal reproducer
Remove unrelated inputs and components while keeping the failure observable. Change one part at a time and confirm that the issue remains. The aim is not the shortest possible code at any cost; it is a case small enough to understand and complete enough to preserve the cause. Keep the original work safe so that simplification does not destroy the context needed to test the eventual correction.
State a falsifiable explanation
Propose a specific cause and predict what observation would follow if it were true. For example, a boundary error should affect a particular class of inputs rather than every input equally. Choose a test that distinguishes that explanation from a competing one. Repeatedly editing code until the output changes can create new errors while leaving the original reasoning unclear. Record what each test ruled out.
Fix the cause and check neighbours
Apply the smallest coherent correction that addresses the identified cause. Test the original reproducer and nearby cases, including relevant boundaries. Passing one example does not establish correctness for all uses. Check that the fix respects the specification rather than merely hiding an error message. Where the project has meaningful automated tests, add a focused case for the failure and run the checks appropriate to the change.
Explain the mechanism
Write a short account of the faulty assumption, the evidence that identified it and why the correction works. Preserve only information useful to a future reader. In assessed programming work, follow rules on external assistance and attribution; being able to run a suggested patch is different from understanding it. A debugging record should improve your next diagnosis, not become a diary of every unsuccessful edit.
