Visual failure clinic

Begin with the symptom, capture the smallest reproducer, then inspect one boundary at a time.

Wrong colors

Check RGB/BGR order, alpha handling, and grayscale conversion. Print one known pixel before and after conversion. Do not compensate with channel-specific thresholds until the I/O contract is correct.

Wrong brightness or wrapped values

Print dtype and range before arithmetic. Convert uint8 to float or a wider integer, perform the operation, clip, then convert back. Look for normalization applied twice or omitted entirely.

Wrong shape

Print at decode, crop, transpose, batch, metric, and save boundaries. Name every axis. Compare expected HWC/CHW and single-frame/batch contracts.

Source changes after cropping

Test whether the crop shares memory with the source. Copy before annotating or mutating when the original must remain stable.

Missing temporal evidence

Inspect timestamps and the sampling policy. Uniform samples may skip a short defect; scene detection may mistake a flash for a cut. Pair any adaptive route with a recorded fallback.

FFmpeg appears successful but output is absent

Capture exit code, stderr, complete argument list, and tool version. Require a zero exit code and expected outputs before writing a success manifest. Avoid shell-string construction.

Metric fires on a valid edit

Preserve the raw score, threshold, and frames that caused it. Add the case to the false-positive gallery, identify missing context, and route ambiguity to human review. Do not silently raise the threshold on the final test set.

Minimal incident record

Record input identity, command/runtime, expected result, actual result, first wrong boundary, minimal reproducer, repair, targeted test, wider verification, and remaining limitation.