Visual Debug

Diagnose an existing implementation against captured reference evidence with structural, AE, DSSIM, runtime, and transition checks.

Boundary and return contract

• Use this skill when reference and implementation evidence already exist. Route missing baseline evidence to ui-capture; route implementation, regeneration, and full clone orchestration to ui-reverse-engineering or the active caller.
• Diagnose and return the failing artifact, selector or region, likely root cause, recommended fix, and exact verification command. The caller owns source edits unless it explicitly delegated repair.
• Read brief/WORKER_BRIEF.md or evidence-pack.json first when present, then only the summaries and named drill-down artifacts needed for the failing hotspot.
• If repair was delegated to you, read ../ui-reverse-engineering/iteration-discipline.md before the repair loop. Attempt history and stop conditions survive delegation and compaction. Report checker defects with a reproducer unless shared-tool repair is already authorized; never edit an installed cache.
• Matching text, heights, fired events, or a successful build does not prove appearance or trajectory parity. Compare background and foreground, media fit, and intermediate motion states.

Required invariants

Do not read ref/impl images for routine comparison. Start with summaries and AE/SSIM tools. For a failing position, run auto-diagnose.sh; read a diff image only if automated diagnosis finds nothing. Phase E is the required exception and must run in a delegated context.

Pin the reference during iteration. Dynamic sites otherwise compare against a moving target: after the first complete reference capture, use frozen reference crops (RECATCH_REF=0) until evidence is genuinely stale. After any implementation edit, produce fresh implementation evidence before judging the fix.

When evidence contains window.scrollTo, scrollYProgress, setTimeout, velocity, a guard ref around scroll-stop logic, or ScrollTrigger pin/scrub, require scroll state-machine proof of initial → active/expanded → settled/returned; a single endpoint frame is insufficient.