Make the bug reproducible

Debugging begins with a repeatable observation. “Sometimes broken” is not enough to tell whether a change helped. If the bug fires 5 times out of 5 before your fix and 0 times out of 5 after it, you learned something. If it was already random, you learned nothing.

Why a vague report is not a starting point

A typical report says “login is broken”. That sentence hides everything you need: which account, which browser, which server, which build, what actually happened on screen. Two people can read it and imagine two different bugs.

Your first job is to turn the report into a procedure someone else can execute. A reproduction card is a short, exact recipe: starting state, actions, actual result, expected result, frequency, environment.

Write a reproduction card:

starting state: signed out, empty local storage
action: open /login, submit valid lab account
actual: spinner remains forever
expected: dashboard loads
frequency: 5 of 5 attempts
environment: Chrome, local server, commit abc123

Every line earns its place. frequency: 5 of 5 tells you the bug is deterministic, so any future run that passes is real signal. commit abc123 pins the code, so you can return to the exact broken version after experiments.

Verify the card actually reproduces

Have another person or a clean browser profile follow only the card. Don’t stand behind them filling in missing steps. If they cannot trigger the bug, the card is incomplete — some precondition lives in your head or your browser. Add any missing precondition they discover.

The common failure mode: the bug reproduces only on your machine because of hidden state. A stale cookie, a local .env override, a cached response. When the clean profile works, that difference is your first clue, not a nuisance. Record it on the card.

Intermittent bugs

When you truly cannot make the failure deterministic, make the frequency measurable instead. “Fails about 1 run in 10 under npm test” still supports experiments. You just need more runs per experiment before you trust the result.

Use disposable accounts and remove secrets, tokens, and private customer data from the reproduction. The card will get pasted into issues and chats, so it must be safe to share.