signature-repro

name

signature-repro

description

Candidate: Root-cause a bug you cannot reproduce because it needs another OS or hardware you don't have, by detecting its structural OR visual signature on the machine you DO have. Use whenever you're about to write cannot-reproduce-needs-Windows/Linux/a-device/a-monitor, when a bug is platform-specific but you're on a different platform, when a visual bug (black rectangle, phantom window, broken layout) supposedly needs a real display, or any moment the honest-but-lazy move is not-reproducible-on-my-machine. For process/install bugs the cause is usually a file descriptor, spawn flag, missing binary, or keychain item observable via lsof/ps/tar/security; for visual bugs, capture the screen and LOOK with your own vision (never a pixel-diff) and cross-check with a window enumeration. Experimental, awaiting baseline evaluation.

Signature over symptom

When a bug is platform-specific and you're on a different platform, the tempting move is "cannot reproduce, needs <that OS/hardware>." That's often a framing error. The symptom may need the hardware; the cause usually doesn't.

A platform-specific symptom is almost always produced by a platform-independent mechanism: a leaked file descriptor, a wrong/missing spawn flag, a window surface that paints wrong, a binary missing from an artifact, a keychain item from a bundle id. Each leaves a structural signature observable on the machine you already have. The bug crashes on Windows, but why it crashes is visible on your Mac. Done well this beats reproducing the symptom: you hand a maintainer the exact fd or missing flag, more actionable than "repros for me too."

Certainty levels — label every finding as one (read first)

A signature is a HYPOTHESIS, not proof. Never say "root cause confirmed" unless you closed the loop.

• CONFIRMED — signature observed AND confirmed (the fix removes the symptom, or a cross-platform run shows the symptom exactly where the mechanism predicts and nowhere else). Only this earns "root cause".
• STRONG HYPOTHESIS — signature observed (a real fd, a missing flag), the mechanism plausibly explains the platform-specificity, but you did NOT confirm the fix works. Most findings land here. Say "suspected cause, by signature".