prove-before-showing

Prove it works before showing it

A build is not proof. A screenshot is not proof. A passing suite is not proof that the thing a human will do actually works. This skill is the checklist that turns "it looks right" into "I drove it and watched it work".

It exists because the alternative was measured. A shell was handed over that rendered pixel-close to its design and was completely inert — not one button clickable — because the verification was a screenshot. And after that was fixed, Build still generated a patch whichever mode was selected, so the headline feature was unreachable, while thirteen tests passed.

The four proofs

Run every one that applies. Each answers a question the others cannot.

1. A/B against the source design

An imported design has a source render. Compare against it, every pass.

# Capture the source. Use the CLI, never the helper directly.
pulp import-design <prototype.html> --output <dir>

# Capture ours.
<app-binary> --screenshot /tmp/ours.png

# Put them side by side and get a number.
python3 tools/rack/compare_renders.py --out /tmp/sheet.png \
  design=<dir>/browser.png ours=/tmp/ours.png rack=/tmp/host.png

compare_renders.py reports the mean per-pixel difference. It is blunt but monotone: it drops when they converge and rises when they diverge, which cannot be argued with the way "looks close enough" can. Track it; do not let it climb.

Name every difference you can still see. A number near zero and a list of five unfixed deltas is honest. A number alone is not.

Traps:

• A DOM snapshot is not evidence of which screen is showing. A self-contained prototype has every heading in its source, so a text search reports success for a click that did nothing. Only pixels are evidence.
• --screenshot captures the render surface, not the composited window. So window-level chrome — rounded corners, shadow, titlebar — will look wrong in a capture even when it is right on screen. Check the running app before "fixing" it.
• The importer captures initial state only today. Multi-screen capture is coming as deterministic CDP actions. Do not inject scripts into the prototype to fake it — that was tried for twelve attempts across four strategies and produced two distinct images.