How to Fix Bugs: A Six-Step Loop That Closes

Fixing a bug means making a reproducible defect stop reproducing, and leaving behind the evidence that it will not come back. The first half is "change the code". The second half is "close it properly" โ€” and most teams only do the first half, so the same problem returns three months later through a different door. Fix quality is not measured by how clever the change was. It is measured by whether the next regression run, the next person to inherit the code, and you in three months can tell from the record alone that it is genuinely gone. This article covers only "how to fix, how to verify, how to close". Which bug to fix first belongs to triage โ€” see the bug triage guide. How to write a report that can be fixed at all is in what a bug report should contain.

The six-step loop

Every step has a minimum evidence requirement. If you cannot meet it, go back a step rather than forward โ€” that is the single most useful rule here.
Step What you do Minimum evidence If you cannot meet it
1 Read Decide whether this report can be started Page URL, environment (browser / OS / version), expected vs actual Send it back for detail; do not guess
2 Reproduce Make it happen once, in your hands One confirmed reproduction, or an explicit "cannot reproduce" conclusion Record what you tried, park it; never close it
3 Locate Find which layer is broken One verbatim error, one failed request, or one bisect result Stop editing; add observability first
4 Fix Remove the root cause with the smallest change One change, one cause Split the commit
5 Verify Prove it is fixed and nothing else broke Same path again + edge cases + regression matrix "Looks fine" is not verification
6 Close Make it readable to the next person One line of root cause + a link to the evidence "Fixed" on its own is not a close

Step 1: Read the report and decide if you can start

A startable report has three things: where, in what environment, and how actual differs from expected. If any is missing, the correct action is to send it back, not to open the code and have a look around. The cost of "have a look around" is badly underestimated. A meaningful share of the pages developers infer after 40 minutes of guessing are not the page the reporter meant. One round of send-back costs two minutes.

Step 2: Reproduce, or explicitly say you cannot

Reproduction is the watershed. A defect that reproduces reliably is only a matter of time to locate. A defect that cannot be reproduced makes any change a gamble. Three things must be pinned down while reproducing, or you are not reproducing the same defect:
  • Data state. Which account, are caches involved, is there stale data in localStorage.
  • Build version. Front-end bundle version, back-end commit, any feature flag that is on.
  • Operation timing. Did they click immediately on load, or after a few seconds, after switching tabs, on a slow connection.
  • If it genuinely will not reproduce, record it as "cannot reproduce" together with three questions, rather than closing it:
    • Which page and which entry point were you on? (The original URL often carries parameters.)
    • Is it tied to a specific account, role or permission?
    • What time did it happen? (If it lines up with a log entry or a deploy, you have a lead.)

    Step 3: Locate โ€” establish the layer first

    Slow fixes are usually not hard problems; they are problems searched for in the wrong layer. Three moves narrow it to one layer:
    Move What you look at What it rules out
    Console The verbatim error and stack Rules out "pure styling / pure data" issues
    Network panel Any 4xx / 5xx, and whether request and response bodies match expectations Separates "the front end never sent it" from "the back end returned the wrong thing"
    Bisect / rollback Which version or commit was last known good Rules out "it was always like this"
    How to read error text: log levels explained and types of errors in programming. How to open the console: open the browser console. For non-developers who want a first look: browser DevTools for non-developers. A concrete decision order: API returns 500 โ†’ back end. API returns 200 but a field is wrong โ†’ contract. API never fired โ†’ front-end logic or validation. API fine, UI wrong โ†’ rendering. Those four lines cover most of what web teams hit.

    Step 4: Fix with the smallest change

    "Smallest change" is not caution, it is verifiability. A pull request that simultaneously fixes the bug, refactors a module and bumps a dependency leaves you unable to say which of the three caused the next problem โ€” which makes step 5 impossible to pass. Two rules:
    • One commit, one cause. If you find a second problem while fixing, open a separate ticket.
    • Refactoring gets its own time. Doing it during a fix mixes known risk with unknown risk.

    Step 5: Verify โ€” prove it is fixed, not hidden

    This is where this article differs from most "how to fix bugs" posts. All four of these make the defect disappear while the problem remains:
    Approach What it looks like What actually happens
    Empty try / catch The error is gone Downstream logic fails silently; data gets written wrong
    Loosening validation No more errors Dirty data enters the database, discovered months later
    Hiding the entry point Users cannot click it The need remains, it arrives by another route, behaviour diverges
    A flag that is never turned back on The symptom stops appearing The flag becomes code nobody dares delete
    The only valid test: can the user now do what they were trying to do? Not "is the error gone". Verification has three parts:
  • Walk the original path โ€” the exact route described in the report, from first step to last.
  • Retry the edges โ€” empty values, very long text, emoji, timezones, decimal money, an account without permission. Those six are where recurrence lives.
  • Run the regression matrix โ€” which old functionality this change could have touched, per how to run regression testing.
  • Step 6: Close with one line of root cause

    Closing a defect with "fixed" pushes the cost onto the next person. A complete root cause note has three parts:
    text
    Root cause: on order submit the form was cleared before the request was sent,
                so a failed request left an empty form; the retry then sent empty
                data, got a 500, and a silent catch swallowed it.
    Fix: send the request first, clear on success; removed the silent catch and
         surfaced an error message instead.
    Verified: Chrome 141 / macOS 14, three retries with the network disabled all
              showed "Submit failed, please retry" and kept the form contents;
              regression: checkout flow, coupons, address book.
    
    Those three parts answer "why it was broken", "what changed" and "how you proved it". They outlive the diff โ€” six months later the diff has been rewritten, the file split, the module replaced, and the comment is still there. Do not leave the evidence in chat only. Screenshots, recordings and failed requests need to live with the record, or three months from now, when regression fails, "what did it look like back then" leads to a dead image-host link. The BugCapturer extension carries console errors, failed requests, page URL, browser and viewport with the submission and produces a shareable link, and reports are retained long-term on the team plan โ€” for one simple reason: so that "the original report still opens" is still true in three months.

    Why reproduction fails: three real causes

    "Cannot reproduce" is a black hole in a defect tracker. It is rarely luck; it is one of three differences. 1. Environment. The usual five: build version (local runs latest main), caches (browser cache, service worker, CDN), feature flags, roles and permissions, timezone and locale. The move is to align those five one by one, not to ask someone to try again. 2. Data. The user's record contains a 300-character note, an emoji nickname, a null middle name, a negative amount. The UI is always correct on "normal data". Whoever can reproduce usually has the specific record ID. 3. Timing. Async races, lazy loading, debounce, third-party callback ordering. These never appear on a fast connection and always appear on a slow one; they are always fine on a developer machine. The tool is throttling and artificial delay, not more logging. When you cannot reproduce, record it as parked + a list of conditions already tried + three questions (entry point / account / time). Closing it is the worst option โ€” you lose the information that it happened at all, and it will come back.

    Patch, hotfix, regular fix: three tempos, do not mix them

    The same bug takes one of three routes depending on impact and urgency, not difficulty:
    Regular fix Patch Hotfix
    Situation Not blocking the main flow, can wait Small scope but needs to ship soon Production main flow down / money at risk / security
    Process Normal iteration with review Goes out with the next minor version Bypasses the normal process, reviewed afterwards
    Mandatory extras Regression matrix Regression matrix + change record Regression matrix + change record + incident review
    Most often missed Edge verification Telling affected users Fixing the symptom, not the cause
    The risk in hotfixes is not speed; it is that nobody goes back afterwards. Temporary changes stay in the code, regression is never added, the review is never written. A hotfix should leave three things behind: a release note, one targeted regression pass, and one sentence on how this reached production at all. Release notes live in the changelog.

    Five rules for the team

    If you only take five things away:
  • Send back the unstartable report; do not guess. Two minutes of send-back against forty minutes of guessing.
  • One commit, one cause. Mixed changes cannot be verified and cannot be rolled back.
  • Close with a root cause and a link to the evidence. The one rule that saves someone a day, six months later.
  • "Cannot reproduce" is a reason to park, not to close.
  • A fix without a matrix backfill is not finished. The row you skipped is where the next incident enters.
  • The boundary between defect, requirement, error and bug gets blurry โ€” see bug vs defect vs issue vs error. If what you need is "how do we tell the client it is fixed", see sharing bug reports with clients.

    Frequently asked questions

    How do I prioritise fixing bugs against new features? By impact times frequency, not by who shouts loudest. The severity-by-priority matrix is in the bug triage guide. The one thing worth adding here: do not re-shuffle the queue mid-sprint. Teams that keep re-triaging usually finish neither track. Can I fix several bugs in one change? Only when it is one root cause and one edit โ€” one cause producing three symptoms is a single bug. Unrelated causes in one commit make rollback impossible: when production breaks you can only revert the whole thing. Does every bug need a unit test? No. Three kinds deserve one: ones that recur (there is a regression record), ones with branchy logic (many edge cases), and anything computing data (money, ratios, dates). Pure display and copy fixes are covered by the regression walkthrough. I found another problem while fixing. Should I fix it too? No. Open a separate ticket. Mixing it in invalidates step 5 โ€” you cannot tell which change made the problem go away. Should we notify users after fixing a production bug? If user-submitted data, money or order state was affected, tell them proactively and say what was repaired. If it was a brief outage that recovered, one status update is enough. Writing it into the changelog also answers "is there any record of this" when a client asks.