Use when building or extending a golden-master/differential conformance harness against a reference implementation — ports, rewrites, legacy capture. Defines the two-tier oracle, determinism engineering at capture time, the divergence-fencing pattern, and the golden ratchet. testing-strategy says WHERE goldens belong; this skill says HOW to build a harness that never flickers and never lies.
89%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
The mechanical form of "the original is the spec." Field-proven shape: a
gitweb port verified 9 endpoint families byte-for-byte against gitweb.perl
with neither perl nor git running at test time, and the byte-exact goldens
surfaced two latent bugs that contains-style conformance checks had
already passed over. Every rule below was paid for.
Before building features, split every output of the system into two tiers and record the split in the parity spec (it is the contract every capability references):
A capability that doesn't know which tier its output is in cannot be specified. The same day-one spec promotes the edge-case matrix to acceptance criteria — merge/multi-parent, rename/copy, mode changes, symlinks, submodules, binary content, empty/unborn state, non-UTF8, pagination boundaries, invalid object — with frequency evidence from the reference source ("~118 merge sites, ~120 rename sites") so nobody can argue they're exotic.
goldens/ with .gitattributes goldens/** binary so git never munges line endings.Each class of volatility has a named technique; pick by class, don't improvise:
| Volatility | Technique |
|---|---|
| Volatile cache headers on some capture paths | Choose the capture path that doesn't emit them (capture by filename, not by hash) |
| Environment-dependent metadata (user names, host config) | Pin it in the corpus so both capture and test read the same value back |
| Genuinely volatile tokens (tool version strings) | Sidecar file: capture writes the token next to the golden; the test reads and injects it, the rest stays byte-exact. Re-capture regenerates both together |
| Clock-relative values (Expires, ages) | Exclude from the golden compare; assert presence/format behaviorally at the boundary |
| Unordered output (directory scans) | Sort before asserting — read order is unspecified |
| Order-dependent fixtures | Strictly-increasing pinned timestamps |
branchname silently re-points when the branch grows; pin
the root (branch~N) explicitly.git diff goldens/ and account for every changed
byte. Unexplained churn means a volatility source you haven't found yet.contains-only suite).When byte-exactness is impossible under your constraints (e.g. the reference's output embeds a compression artifact you cannot legally reproduce), the divergence is never silent. The pattern:
scripts/golden-audit.bb checks golden↔test
linkage both directions (orphan goldens, references with no file on
disk — the must-panic case caught early), untracked captures, and the
.gitattributes binary rule. Run it after wiring a new endpoint and
after any re-capture.igouss/gitweb-rs
9ef2429
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.