How to raise a bug

Classify it before you write a word

Three destinations, one question each.

Did someone approve this behaviour and did we ship something different? Bug, under the quarter's Bug Budget epic. Did nobody ever agree it? New scope: a story under an existing epic, or a new epic if it carries its own value. Is the defect invisible to users and painful only to engineers? Tech debt, under the quarter's Tech Debt epic. Read the source before you decide: the acceptance criteria on the story, or the user journeys and test requirements on the outcome ticket in an AI-native team. Where the source is silent, it is scope, not a bug.

Reproduce it three times, then record the path

Write steps a stranger can follow without asking you anything: environment, build or release version, account type and permissions, data state, the exact input, and the timestamp of an occurrence you watched happen. Run it three times and record the hit rate, three of three or one of five, because intermittency changes both the fix and the test. Attach a request or trace ID, the log lines either side of the failure, and a short screen recording. If you cannot reproduce it, say so in the first line rather than leaving it implied, and list what you tried, how many users hit it per day, and where you stopped.

State expected against actual, cite the source

Two sentences, then a title.

Expected: the behaviour that was approved, quoting the acceptance criterion, user journey or test requirement it comes from, with a link. Actual: what happens instead, in the same terms. Citing the source is what stops triage becoming an argument about whether anyone agreed the behaviour. Title in the shape area, what breaks, for whom, under what condition. "Checkout: card payments over £500 fail for guest users with a generic error" beats "payments broken". Keep your theory of the cause out of the title and put it in the body, labelled as a theory.

Set severity by impact, then price it

Publish a rubric and hold to it.

S1: a key journey cannot be completed, no workaround exists, or there is revenue, safety or regulatory exposure. S2: a key journey is degraded and support can talk a user through a workaround. S3: everything else, including cosmetic defects and edge cases with negligible reach. Then price it: affected users per week times the value lost per affected user, using the conversion and basket numbers the parent outcome was priced with. A weekly cost in currency makes the bug rankable against features. One named person may downgrade a severity, and the reason goes in the ticket.

Link it to the budget and its origin

Attach every bug to the current roadmap's Bug Budget epic, so the chain from defect to priced outcome stays intact.

Then add the link most teams skip: the epic, story or release that introduced it, traced from the release that first shipped the broken behaviour. Keep an "introduced by" field and leave it empty rather than guessing. That backlink turns the budget from a bucket into three numbers at quarter close: burn against forecast, defects per epic, and the severity mix quarter on quarter. Without it you have a count of bugs, which measures how busy you were.

Make the rollback call explicitly

Anything found inside the seven-day live monitoring window gets a continue, watch or roll back call from a named person, on the record, rather than by drift. Compare two numbers you can write down: exposure per day in currency, and hours to a fix you would trust. Roll back when exposure per day exceeds what the epic earns per day and the trusted fix is more than a day out, or when you cannot yet bound the blast radius. Record the call, both numbers and the reasoning in the bug, including a decision not to roll back, because the root cause analysis will ask.

Size it and schedule it against the budget

Bugs go through refinement and sizing like everything else, and through the same phases: todo, in progress, in review, done.

Set the budget from your own data, taking the capacity defects consumed over the last three quarters as a percentage of throughput and reserving that much. It is a forecast, not a permission slip. S1s interrupt the sprint. S2s are scheduled inside the quarter. S3s compete on value with everything else, and some should be closed unfixed with a note saying so. Past half the budget before half the quarter, raise it at the next monthly health check while there is still quarter left to react in.

Fix with a failing test, close with evidence

Write the regression test first and watch it fail on the affected build.

A fix with no test that failed beforehand is a claim, and it is why the same defect returns two releases later. Name the test and the failing build in the ticket so the next person can rerun it. Close when the test passes, a human has reviewed the change, product has approved it, and the behaviour has been demonstrated in the environment where it was reported, not only in staging. Book the root cause analysis for any S1 before you close, and investigate the system that let it through, not the person who wrote the line.