The Brief Was Right. The Build Wasn't Wrong Because of the Brief.

A mate of mine asked me recently why I bother writing about the failures instead of just shipping the win and moving on. Fair question. Here's the honest answer: the wins don't teach anyone anything. This one did.

I was building a live gauge for ASOR's on-screen graphic - the sigil (our triangle mark) needed to fill up like a progress bar, in real time, driven by a rider's heart rate, power, and cadence. Three arms, three metrics, each one filling independently. Sounds simple. It is not simple, but that's not the point of this post.

The point is this: I gave Claude Code a precise brief. Annotated diagrams. Ten-segment breakdowns of exactly where the fill should start and stop. Six mockup images showing the gauge at 5%, 20%, 40%, 50%, 80%, and 100% fill. I wasn't being vague. I wasn't hand-waving "make it look good." I handed over the equivalent of a dimensioned drawing.

And it still failed. Six times. Across roughly 250,000-300,000 tokens.

The brief wasn't the problem

Now you might be thinking: surely if it failed six times, the instructions must have been unclear somewhere. I went back and checked. They weren't. Every reference image was unambiguous. The task description, read back to me before each build, sounded exactly right.

What was wrong wasn't the brief. It was the input data underneath the brief - the actual coordinates of the shape being filled.

Here's the analogy, and it's close to home from my industrial design background (it's not like you turn that way of thinking off): you can write the most detailed spec sheet in the world for a part, but if the actual measurements on the manufacturing jig are off by a few millimetres, every single thing built from that jig is going to be wrong in the same way. Doesn't matter how good the spec was. Doesn't matter how many times you re-read it. The jig is wrong, so the parts are wrong.

That's what happened here. The "jig" was a handful of estimated coordinates on an SVG shape - landmark points like "this is roughly where the elbow of the triangle's arm sits." Close enough to look plausible. Not accurate enough to actually work.

Six different tools, one bad input

What got me was watching the pattern repeat with completely different techniques each time:

1. Subpath masking - clip the fill to the exact pixel boundary of each arm. Should be foolproof. Wasn't, because nobody had confirmed which subpath corresponded to which visible arm. Guessed wrong.
2. Corridor clipping - build a strip around the spine of the arm, width X. Width was wrong (too narrow, then too wide - bled into the next arm).
3. Zone polygon + fill - turned out to fill the hollow centre of the triangle instead of the arm itself, because of how the fill rule interpreted the overlapping shapes.
4. Stroke + clip (attempt one) - line too thick, bled past the joints.
5. Stroke + clip (attempt two) - line width tightened, but now it bled the other direction, into the triangle's interior.
6. Stroke + clip + zone polygons - still off. Put on hold here.

Every single one of those was a genuinely different engineering approach. Not the same mistake dressed up six ways. Six real attempts to solve the problem. And every single one inherited the same slightly-wrong coordinates from the attempt before it.

That's the bit worth sitting with. Six failures that look like six different problems are sometimes one failure, wearing six different costumes.

The diagnostic it proposed - and I turned down

Here's the part that actually stings a little, in hindsight. At one point, after two failed attempts, it suggested painting each of the three arm shapes in solid red, green, and blue - just to see, visually, which shape was actually which. A pure diagnostic. No fill logic. Just "let's measure before we guess again."

I said no. I wanted a working gauge, not a colour-coded triangle. So we skipped the fifteen-minute measurement step and spent another four attempts (and a lot more tokens) iterating on guesses instead.

Firm but fair to myself here: that was on me, not the tool. I had a chance to stop and measure, and I chose to push for the finish line instead. Classic "I don't have time to do this properly, so I'll do it five times instead."

The actual lesson

If there's a bumper sticker version of this, it's: measure before you iterate.

Not "give better instructions." Not "use better prompts." The instructions were fine. The reference images were fine. What was missing was ground truth on the thing being manipulated - and no amount of re-explaining the goal fixes a wrong number sitting underneath it.

This matters beyond gauge graphics. Any time you're working with an AI system (or honestly, any system) on something visual or spatial, the question worth asking isn't just "did I describe what I want clearly enough?" It's "does the model actually know where things are, or is it estimating?" Those are very different failure modes, and they look identical from the outside until you stop and check.

I'm going to start building that check in earlier. A quick "show me what you think the shape actually is" step, before asking for the fix. Cheaper than six attempts. Probably should've been attempt one.

• Jason