The sessions / Prompts & Workflows

Two real bugs on this site's signature design component were caught by looking at the page, not by reading the code; the four-step discipline that fixed them is one anyone can run.

4 min read

Read as: HTML / Markdown

When I asked a model to list the questions a beginner would ask about building with AI, this was one of them, and the model answered it too: you do not need to read the code, just describe the symptom. That answer is half right, and the half it keeps matters, because a precise description of what you saw is the single most useful thing a non-technical person brings to a bug. The half it drops is the discipline that makes a fix real. So I put it to the test on this site, fixing real bugs with Claude Code by describing what I saw. One component here produced two bugs eleven days apart. I caught both by looking at the rendered page, not by reading the component, and the second is the honest part of the story: three attempted fixes in a row chased a guessed cause and failed, before one measurement ended it.

What makes a good bug report?

Speak like a witness: what you did, what you saw, and where. Not “the animation looks broken” but “when I click reset, the labels on the left jump down in blocks”. That is a report a model can act on, and none of it needs you to read a line of code.

So how do you fix it without reading the code?

Hold the model to four steps, none of which needs you to read a line:

1. Reproduce it. If the model cannot make the bug happen on demand, it is guessing.
2. Measure it. Ask for numbers: how big, how often, exactly when. A defect you can measure is a defect you can prove fixed.
3. Name the mechanism. Before any fix, the model states why the bug happens, in one sentence you can repeat back. A fix without a named mechanism is a coin toss.
4. Fix the class, not the symptom. Ask what else the same mechanism could break, and fix that too.

Then the reporter’s second job, the one that quick answer leaves out: look again. A bug is not fixed because the model says so; it is fixed when you have seen it stop happening.

Where can I see this on the site?

Both bugs came from one component: the split-flap number, the departure-board figure that rolls a headline number into view. It was on the home page when these bugs were found; the fixed version now rolls the Field Test scoreboards, holding its height steady exactly as these two catches taught it to.

The first catch, 7 July 2026.

• The problem I saw: when the numbers rolled, the sentence beside each board shook left and right.
• The mechanism: an animation swapping glyphs inside a content-sized box reflows whatever sits next to it.
• The fix: give every flap cell a fixed width, sized to the widest glyph, so the board holds its size for the whole roll.

The second catch, 18 July 2026, the one that teaches the most.

• The problem I saw: on a scoreboard built from the same flaps, clicking reset rolled the numbers fine, but the labels on the left jumped down in blocks as the roll swept past.
• The false starts: three fixes chased that symptom as a repaint or timing problem, and none of them landed.
• The measurement that ended it: the model sampled the live roll and measured the board’s height dropping from 30px to 6px mid-roll, and the mechanism finally had a name. The flaps turn through a blank glyph, and a cell showing only the blank has no text line to hold it, so it collapsed for a few frames and shoved every row below it down the card.
• The fix: one line, a minimum height. The height twin of the first catch’s width fix, the same class of defect on the other axis.
• The proof: I did not call it done until I had seen it hold on my own device. On the live roll the blank still appears, the board holds at 30px, and all nine row labels stay put to the pixel.

So can you fix a bug you cannot read?

You can, and what you cannot skip is looking. The same symptom, Claude chased as a guess, bought three fixes that did not hold; one measurement ended it. So describe what you saw like a witness, make the model reproduce it, measure it and name the mechanism before it touches anything, ask it to fix the class rather than the instance, and then look at the page yourself before you call it done. Reading the code is the model’s job. Verifying the result never stops being yours.

Where my approach differs from that quick answer, the difference is deliberate: the contrast is part of the teaching.