Use behaviour-equivalence

Prove that a rewritten, migrated or refactored component behaves the same as the old one with a golden-master comparison

Prove that a rewritten, migrated or refactored component behaves the same as the old one with a golden-master comparison — record inputs and outputs at a boundary (HTTP, function calls, batch files, DB writes, events) from production-shaped traffic and edge cases, run the old system twice to find its nondeterminism, normalise narrowly field by field, replay against the new one, triage every difference as defect, intended change (with a named approver) or missing normalisation, and give a verdict of EQUIVALENT, EQUIVALENT EXCEPT LISTED CHANGES, NOT EQUIVALENT or NOT PROVEN.

Reach for it when the user asks "does the new one behave the same as the old one", "can we sign off the rewrite", "are these diffs just noise", wants a golden-master, approval or shadow-traffic comparison, a parity check between old and new outputs, or says "prove behaviour equivalence".

Install it

npx skilldrop-cli install behaviour-equivalence                 # Claude Code, your user folder
npx skilldrop-cli install behaviour-equivalence --project       # Claude Code, this repo
npx skilldrop-cli install behaviour-equivalence --ide cursor    # or kiro, codex, antigravity, copilot

It is part of the Dev team pack: --pack dev-team installs it with its neighbours.

It ships scripts, so it needs Python 3 (standard library only, nothing to install). What they may touch is declared in its manifest.

Ask for it

Say it the way you would to a colleague. Requests like these route to it:

• "We ported our tax calculation from Java to Go. I have recorded outputs from both on 2,000 real invoices. How do I prove they behave the same?"
• "Our shadow-traffic diff between the old and new checkout API shows a bunch of differences. Are these just noise or real regressions?"
• "Set up a golden master comparison for the legacy report generator before we replace it"
• "The new billing service matches the old one apart from some timestamps and a few 1p differences. Can we sign off parity?"
• "Review these normalisation rules for our approval tests and tell me if they hide anything"

Requests like these belong to a different skill, so it shouldn't answer them:

• "Plan how we break up the 3,000-line OrderService into smaller pieces without stopping feature work"
• "Write a phased plan to move our orders table from MySQL to Postgres with a backfill and zero downtime"
• "Write a test plan for the new loyalty-points feature before release"

If another skill answers instead, ask for this one by name: "use behaviour-equivalence".

Check what you get

A good result:

• The first line is one of the four verdicts with the reason in plain words.
• Every difference is classified as defect, intended change or missing normalisation; none is left as "minor".
• Every normalisation rule names one field and a reason, and the field varied old-vs-old.
• Money is compared exactly in minor units; any float tolerance is per field with a reason.
• Error behaviour and side effects are compared, not only return values.
• Coverage is stated by input class, and the verdict covers only the recorded classes.
• Intended changes name an approver from the input, or stay unresolved.
• Every case id, value, count and cause is from the input or the script output.

See a worked example

• delivery date

Use something else when

• Planning the refactor or rewrite steps themselves — refactor-plan
• Phasing a data or platform migration, backfill and cutover — migration-plan
• A test plan for a new feature or changed behaviour — test-plan-generator
• Getting oriented in the old codebase before starting — codebase-tour

Where a loop runs it

• Stage capture of the modernize loop
• Stage prove of the modernize loop, where gate G10 decides

Next

• SKILL.md, the instructions the agent reads
• Its page on the site
• Related: codebase-tour, migration-plan, refactor-plan, test-plan-generator

Edit this page on GitHub · View source