Five rewrites, back to version two — what I was missing wasn't a better diagram, it was a rubric

2026-07-14 · build log of an explainer-video engine

I'm building an explainer-video engine, with a set of renderers that show physics misconceptions. One draws a force analysis. I rewrote the preview five times — then looked back and realized I'd landed on roughly what version two already was. The whole middle was spinning in place.

Last post, AI 译匠, I said a validator and a loop are a pair. That assumed you can write a validator. This time you can't: the DOM can't compute "is this diagram any good," and I have no gold-standard diagram to compare against. So I was back on the slot machine: tweak, eyeball the preview on gut feel, tweak again — win a round with no idea why.

The problem wasn't the diagram. It was that I was the judge, with no rubric, showing up only after the thing was built. The moment I forced the rubric onto paper, why the five versions spun was obvious:

Before: abstract arrows floating on a grid — Before: abstract arrows on a grid, F₁/F₂/resultant piled on the box — a textbook schematic the student has to translate in their head first.

After: a concrete inclined-plane scene — After: a concrete incline — block, θ=30° — where "normal force ≠ gravity" is right there to see.

The flaws you can stare at a preview and "feel" for ages without catching are, on the rubric, a few lines in black and white. It looks like this (other problems get their own, same method):

Force-analysis spine · rubric (score each; if it fails, give a fix)
1 Concrete first        A real scene (incline + block), or a pile of abstract arrows?
2 Cognitive load        How many quantities on screen? Split past 3–4.
3 Visual/narration parity Every force the narration names — is it drawn on screen?
4 Causality visible     Does the student SEE why, or get told the conclusion?
5 Misconception target  Which misbelief does this break? Do the visuals hit it head-on?

The takeaway, one line: before you start, ask — who's the judge, by what standard, and is that judge in place? Sort the work by how correctness gets established:

Tier	Judge	Device (before you build)
Deterministic	Validator / test	Freeze cases first, then implement (TDD)
Creative · subjective	Domain-expert panel + explicit rubric	At the proposal stage: N approaches → score → converge → then build
Conversational	Eval + LLM judge	Build the scenario set first

Force analysis is that middle tier — the one I'd never built a device for, which is exactly why it was the one spinning. Decide the judge first, then build.

I've packaged this into a Claude skill, open-sourced on GitHub — clone it into ~/.claude/skills/ and it's yours to use.

Honestly: I only built this rubric today, haven't run it across the spines yet. By the last post's rule — don't even trust your own validator — I'll brag once I've run it and posted real numbers. One aside, since it's ours: leonclass.com, which helps science teachers vet exam questions, is this same shape — the checkable half goes to code, the teaching-judgment half makes the teacher the judge, with a clear rubric in hand.

If you're also chewing on verification / education / agents, come say hi.