The first user complaint

“It doesn’t work”

That is the whole message, most of the time. No page, no time, no screenshot. It is not the user being unhelpful; it is what a problem looks like from the other side, where there is no log and no stack trace, only a button that did nothing.

The work of this lesson is turning that sentence into a line in a log, and then into a fix, and then into something that cannot happen again.

Before the first complaint: the reference id

Generate an id per request (a short random string) and put it in three places: the log line for anything that happens during that request, the error tracker’s event, and the error message shown to the user:

Something went wrong saving your booking. Reference: k7q2-4mzd. It has been reported.

Now a user who writes “it said reference k7q2-4mzd” has handed you the exact log line, and the search takes seconds. Most frameworks and hosts either provide a request id or make it a middleware of three lines. It is the highest-value ten minutes in this block.

The three questions

When the message has no reference, ask three things, and only three, because each extra question halves the chance of an answer:

1. Which page, or what were you trying to do?
2. Roughly when: today, an hour ago?
3. What did the screen show: an error, nothing, the wrong thing?

While waiting, search. The email’s timestamp and the user’s account narrow the logs to a few minutes and one user id. A 500 in that window is the answer. A 200 in that window with no error means the third kind of broken from the previous lesson: it worked and it was wrong, and you need the user’s description of what “wrong” was.

Seeing what they saw

Two tools for the case where the logs are clean.

View as user, for admins: a way to open the app with a given user’s data, read-only, with an audit row recording that you did. It shows the empty state they see, the booking they cannot find, the date that rendered wrongly for their time zone. Build it with the admin protections from the security block, because it is the most powerful page in the app.

A copy of their situation on the preview. Their account’s shape (a user with forty bookings, one cancelled, in a different time zone) recreated by the seed script against the preview deployment. This is the reproduction the breaking block insisted on, done with a real shape instead of a guessed one.

The reply

Once you know:

Found it: bookings made after 11pm were being saved with the next day’s date because of a time zone mistake on our side. It is fixed as of this afternoon; your booking for the 30th is now showing correctly. Thank you for telling us.

What happened, that it was yours, that it is fixed, and that their specific case is right now. No “we apologise for any inconvenience”; the sentence about their booking is the apology. If it is not fixed yet, say when you expect it to be and write again when it is.

The fix ends with an item

The breaking block ended a fix with the question “was it actually fixed”. This block ends it one step later: the failing case becomes a permanent test. A row in the eval set if it was the AI feature, a test in the test suite if it was code, an entry in the three-account script if it was access. Every complaint that reaches you is an example nobody on your side thought of, and it is worth more as a test than as a memory.

The complaint that is not a bug

Some are misunderstandings: the feature works and the user expected something else. That is still information (the label was unclear, the button was in the wrong place, the empty state did not say what to do) and it goes into the same list with a different tag. A feature that three people misunderstand the same way has a design bug, whatever the code says.

Keeping the list

One table or one document: date, user id, what they said, what it was, what changed. In three months it is the truest account of what the app does badly that exists, and the first thing a developer you bring in will ask to read.