design-judge

Files (2)

• SKILL.md
• ai-slop-checklist.md · references/

SKILL.md (first lines)

# design-judge

> **v3 · 2026-08-04.** Hardening pass: added the Harness & verification traps section —
> static harnesses built from `outerHTML` drop IDL state and produce phantom vetoes,
> preview screenshots blank after any DOM mutation, CSS claims must be checked by
> computed style + real interaction (never your own stylesheet), and immutable-cached
> assets need an explicit cache-bust before a lens screenshots the "new" version.
>
> Prior **v2 · 2026-07-25.**
>
> Prior **v1 · 2026-07-15.**

This is an evidence-scoped review protocol. It makes rendering, approved baselines,
proof checks, and unresolved findings explicit; it does not replace a qualified design
reviewer or make a model-superiority claim.

## Iron rules (before any judgment)

1. **Nothing is judged unrendered.** Render the artifact and screenshot it — the diff
   looking right has lied before (92 deck layout defects, once). Restart the preview
   after template edits, and bump the `?v=` cache-buster on every edited linked asset
   before judging — an immutable-cached surface renders fine cold and stays broken
   for returning visitors (caught twice on one product hub: 2026-07-16 gate run,
   2026-07-20). Use the
   headless-render toolchain for decks (qlmanage/PIL/PyMuPDF). Judge the pixels, not
   the code.
2. **Mechanism before surface.** First
   question is never "is it pretty" — it's "is the underlying mechanism right?" A
   motif repeated 3+ times, or a component needing an exception every reuse, is a
   mechanism problem: kill it, don't polish it (plan-card motif → one Prediction
   Engine; navy band → invisible scaffold).
3. **Proof honesty is a veto, not a score.** Testimonials, counters, logos, case
   studies: real artifact or explicit "illustrative" label — or the surface doesn't
   ship regardless of how good it looks (precedent: fabricated testimonials found on
   a live marketing homepage; a "redacted case-study" proof card vetoed on another
   surface until a real engagement existed). Positive reference: unitedcarriers.com
   stacks stats + testimonials + partner logos + case studies in one scroll, all
   traceable — see the harvested anti-cliché catalog below for detail.
4. **Regression is a veto too.** On any previously-approved surface (a product hub, a
   slide-deck template, a homepage redesign), judge against the last APPROVED render,
   not against nothing — copy-pasted sections, fallback styles and template defaults
   reintroduce dead looks (a deck reskin killed an approved header-band treatment;
   the lesson learned was "don't revert to the old default" precisely because a
   template default could bring it back). A lens that
   finds an approved decision silently reverted vetoes regardless of score.
   (fleet-orchestrator gate class 3.)

## Harness & verification traps

Checks inside the render→lens→verdict loop, not a new philosophy — each has cost a
full judging round when skipped.

- **Static harness ≠ live page.** A harness rebuilt from `element.outerHTML` (the
  fallback when the real page won't screenshot) drops IDL state — `select.selected`,
  `checked`, `value`, `indeterminate`, scroll position never serialize as attributes,
  so a correctly-placeholdered dropdown falls through to its first enabled option in
  the harness alone. A lens VETO sourced from a static snapshot is a phantom defect
  until re-verified against the LIVE DOM (`javascript_tool` inspection) — precedent:
  a mechanism-lens veto on a dropdown that was actually fine, 2026-07-31. Also don't
  hand-abridge harness data (a truncated option list reads back as a product defect).
- **Harness-specific screenshot failure.** If a screenshot is blank or stale after a
  mutation, reproduce it with the recorded renderer, viewport, and action sequence.
  Do not generalize one harness failure to every renderer. Never score an unusable
  capture; refresh or rebuild the view and record the successful capture path.
- **Verify by computed style and real interaction, never your own CSS.** A global
  reset can silently strip what your stylesheet promises — `buttons.css`'s
  11-`:not()` reset zeroed a new button class's border and clipped its focus ring
  while the authored rule read fine on paper. Assert `getComputedStyle`, not source
  text, and drive focus states with an actual Tab keypress (`.focus()` under-reports
  `:focus-visible`).
- **Stale-asset false-pass.** Immutable-cached static assets serve the OLD file to a
  lens screenshot unless the referring page's `?v=`/`?fresh=` is bumped first — same
  failure as iron rule 1's cache-buster clause, but it also fires mid-panel: a lens
  can screenshot a "fixed" surface that's still serving the pre-fix asset.
- **Screenshot path.** For pixel-only review, use an installed, pinned renderer that
  the active harness can run. Do not fetch an unpinned package during review. Use a
  browser-capable path for computed style, IDL state, or real keyboard interaction.

**Observed vs. inferred — label which is which.** A screenshot is evidence of exactly one
viewport, one theme, one state, at one moment. Everything the surface *implies* beyond that
— breakpoint behavior, hover/focus interactions, scroll choreography, loading and empty
states, real asset fidelity — is **inferred** until separately rendered and captured. Say
which is which in the verdict: an inferred claim recorded as observed is the same failure
class as an errored lens counted as a pass. Specifically, **a still frame cannot establish
motion** — judge animation, transitions, and scroll behavior against captured behavior (a
recording, a stepped capture, an interaction trace), or mark that lens OPEN. And compare
like with like: the judged render must match the reference's viewport dimensions with fonts
and assets actually loaded, or a spacing/typography "mismatch" is an artifact of the harness
rather than the design. Correct structural, spacing, and typography mismatches before
judging decoration.

## The panel

For a real-audience or high-stakes surface, use an appropriate independent verifier and
more than one distinct lens when the stakes justify it. Smaller or internal iterations
may use one reviewer with a stated scope. Never count repeated copies of one lens as
independent review; select available approved roles without model-comparison claims.

**Hand every judge the complete render package. A lens must never rediscover or substitute its
own render** — two judges scoring two different captures is not a panel, it is two opinions with
a shared vocabulary, and the disagreement it produces looks like a real finding. Each dispatch
carries, explicitly:

- `candidate_render` — the exact file path of the capture under judgement.
- `approved_baseline` — path, or the literal `none`. This is what wires iron rule 4: without it
  a judge cannot tell a regression from a choice.
- `artifact_context` — what it is, plus viewport / page / slide number, and which interaction
  state is shown (default, hover, error, empty, loading).
- `proof_inventory` — every proof element visible in this capture, so trust & proof judges the
  page in front of it rather than hunting.
- `capture_trace` — how the render was produced (URL/command, cache-buster, fonts loaded), so a
  harness artefact is separable from a design defect.

Each judge returns `status: COMPLETE | OPEN`. `OPEN` is the machine-readable form of the
errored-lens rule below — a lens that could not judge must not be silently counted as one that
found nothing.

**mechanism is mandatory** on every panel, and **trust & proof is mandatory** on any
surface carrying proof elements — they are the only executors of iron rules 2 and 3,

From chandel-workspace/fleetcraft, MIT.

More from chandel-workspace/fleetcraft