Look at it before you call it done
Zero type errors, 124 passing tests, clean audit, successful build. Broken page.
A change to a quiz app passed the type checker with zero errors, a hundred and twenty-four unit tests, a design-rules audit, and a twenty-page build. The agent reported it done.
The page rendered edge to edge with no padding, every answer button unstyled, and the footer painted over the navigation. Every automated gate was green. The only thing that caught it was a screenshot.
This is the most important lesson on the site, and it is the one agents resist most, because they are good at the gates and the gates said yes.
Why the gates could not see it
The three defects were invisible to the suite by construction:
- A container class was dropped from a
mainelement. The class supplied margin, padding and max-width. No test asserts padding. - Scoped styles in the framework only reach elements that exist at build time. Anything created by script never gets the scoping attribute, so every rule for it silently fails to match. The buttons were created by script.
- The body was a flex column, so
mainwas a flex item that could shrink. Give it its ownmin-heightand it collapses to that height and its children spill under the footer. Layout is not a type.
None of these are exotic. All of them are the kind of thing an agent adding a feature does without noticing, because it is reasoning about behavior and the defect is visual.
The rule
Never ship a UI change you have not seen rendered. Take a screenshot, open it, and look. This applies to agents as strictly as to people.
The monorepo has a one-line tool that shoots a running dev server at phone width and desktop width, in light and dark. The agent runs it, then reads the image back. Checking that the command exited zero is not looking.
Minimum evidence
Phone width in light, phone width in dark, one desktop width. If the change has a state, such as an answered question, an open menu, or a running simulation, drive the page into that state and shoot it too. A screenshot of the idle page says nothing about the answered page.
Keep the shots outside the repo, in a runs directory, and mention their path in the handoff so the next session can look without regenerating.
What an agent can and cannot see in a screenshot
Modern agents read images well enough to notice missing padding, a button with no border, text overlapping a footer, and a canvas that is a solid block of accent color. They are worse at subtle misalignment and at “this looks slightly wrong.” So the screenshot check catches the big breaks, which is where most of the damage is, and you still glance at the result yourself before merging.
The generalization
The suite tests what someone thought to test. It cannot tell you about the failure mode nobody has had yet. A render, a curl of the live URL, a tap on the phone: these are checks against reality rather than against expectations, and reality is the thing you ship to.
Green means the checks you wrote passed. It does not mean the thing works. Look at it. Then let the agent call it done.