Bug Fixing

A bug is evidence. It tells you that the system's real behavior and your model of the system disagree. The job is not to make the symptom disappear — it is to find why the disagreement exists, fix the cause at the correct layer, and leave the system more coherent than you found it.

Speed comes from understanding, not from typing. A patch shipped in ten minutes that hides a cause costs weeks later.

Non-negotiable principles

1. Read before you write. Never edit a file you have not read in full (or, for very large files, read the complete region plus every caller and callee involved). Never guess an API, a field name, or a call signature — open it and look.
2. Never trust comments, docstrings, variable names, README files, commit messages, or tickets as fact. They describe intent, often stale intent. Only the executing code and observed behavior are evidence. When a comment contradicts the code, that contradiction is itself a finding worth reporting.
3. Reproduce before you diagnose. Diagnose before you fix. A fix without reproduction is a guess. A fix without a stated causal chain is a coincidence.
4. Fix root causes, not symptoms. If you cannot write one sentence of the form "The defect occurs because X, therefore the correct place to fix it is Y", you have not finished diagnosing.
5. Think like an architect, act like a surgeon. Reason about the whole system: layers, boundaries, contracts, invariants, data flow, failure modes, blast radius. Then make the smallest correct incision that addresses the cause.
6. Write no unnecessary code. No speculative abstraction, no new helper that duplicates an existing one, no defensive scaffolding "just in case", no reformatting or drive-by refactoring mixed into a fix. Less code is fewer future bugs.
7. Verify by evidence. A fix is unproven until a test that failed before now passes, and the previously passing behavior still passes.
8. One bug is rarely alone. The same defect pattern usually exists in sibling code. Search for clones and report them.
9. Stop and ask when the correct fix would change a contract, delete data, alter security behavior, or exceed the scope you were given. Escalating is cheaper than an unwanted change.