Skill

Compare two code versions for semantic equivalence

A Logic-Lens skill for semantic diffing two code versions via semi-formal tracing to confirm behavior is unchanged.


73
Spark score
out of 100
Updated last month
Version 0.6.7

Add to Favorites

Why it matters

Verify that refactored, rewritten, or migrated code behaves identically to the original version by tracing both implementations side-by-side through common and boundary cases to catch unintended behavioral changes.

Outcomes

What it gets done

01

Trace both code versions through the same inputs to find the first divergence point

02

Test boundary cases like empty inputs, nulls, max/min values, and error conditions in parallel

03

Classify each semantic divergence with premises, trace steps, and remediation guidance

04

Issue an equivalence verdict: semantically equivalent, conditionally equivalent, or divergent

Install

Add it to your toolbox

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/ag-logic-diff | bash

Overview

Logic-Lens - Semantic Diff

This Logic-Lens skill semantically diffs two code versions via semi-formal tracing, producing a Premises/Trace/Divergence/Trigger/Remedy finding for each behavior change plus an overall equivalence verdict. Use it after a refactor, rewrite, or migration to confirm behavior is unchanged. Falls back to logic-review when only one code version is given.

What it does

A Logic-Lens skill for semantic diffing: comparing two code versions side-by-side via semi-formal tracing to confirm whether behavior is unchanged after a refactor, rewrite, migration, or A/B implementation. It uses lazy loading of shared reference docs (common.md for language, Iron Law, Verdict header, scope routing, and config; logic-diff-guide.md loaded step by step; logic-risks.md, semiformal-guide.md, semiformal-checklist.md, and report-template.md loaded on demand) to keep context usage low. The process runs eight steps: Step 0 detects language and confirms two versions are provided, falling back to logic-review if only one version exists. Step 1 identifies the shared specification - what inputs and outputs both versions should handle - and records any user-declared intentional behavior change as a declared spec change, so divergences within that stated area are treated as expected rather than flagged. Step 2 builds independent premises for each version separately using the Premises Construction Checklist. Step 3 traces both versions in parallel on the common case, noting the first point of divergence. Step 4 traces boundary cases - empty/null/zero, max/min, error inputs, first/last of collections - starting with at most three highest-risk scenarios unless the user asks for exhaustive equivalence. Step 5 classifies each semantic divergence as a finding with the five-field format: Premises, Trace, Divergence, Trigger, Remedy, plus an L-code. Step 6 issues an equivalence verdict: Semantically Equivalent, Conditionally Equivalent (with the condition stated precisely), or Semantically Divergent. Step 7 outputs the Report Template with the Verdict header, localizing headers if the user wrote in Chinese. The mode line in the report reads "Semantic Diff" (语义对比 in Chinese). Formatting is mandatory even for trivially short snippets - every divergence finding must use all five labeled fields, never a plain paragraph or table.

When to use - and when NOT to

Use it when comparing two code versions for semantic equivalence after a refactor, rewrite, migration, or A/B implementation - the trigger phrases are "did I break anything", "is this equivalent", or similar. Switch to logic-review instead if only one code version is provided rather than two.

Inputs and outputs

Input is two versions of code plus, optionally, a user-declared statement of intentional behavior changes. Output is a structured equivalence report: an Equivalence Verdict line, and for each divergence found, a finding block with Premises, Trace, Divergence, Trigger, and Remedy fields plus an L-code classification.

Integrations

Part of the Logic-Lens skill family, sharing ../_shared/common.md, ../_shared/logic-risks.md, ../_shared/semiformal-guide.md, ../_shared/semiformal-checklist.md, and ../_shared/report-template.md with sibling skills logic-review, logic-locate, and logic-explain, and handing off to logic-review when only one version is available.

Who it's for

Developers who need rigorous confirmation that a refactor, migration, or rewrite preserves behavior - not just a visual diff, but a semi-formal trace of both versions against boundary cases before signing off on equivalence.

Source README

Logic-Lens - Semantic Diff

When to Use

Use this skill when you need compare two code versions for semantic equivalence via semi-formal tracing of both versions side-by-side. Trigger when the user shares a refactor, rewrite, migration, or A/B implementation and wants to confirm behavior is unchanged - "did I break anything", "is this equivalent", "are...

Setup

Use lazy loading per ../_shared/common.md §13:

  1. Read ../_shared/common.md only for language, Iron Law, Verdict header, scope routing, Remedy discipline, config fields, and loading budget.
  2. Read only the relevant step in logic-diff-guide.md as you reach it.
  3. Load ../_shared/logic-risks.md, ../_shared/semiformal-guide.md, ../_shared/semiformal-checklist.md, and ../_shared/report-template.md on demand when the current step needs them.

Process

Step 0. Language + scope routing. Detect language per common.md §1. Confirm two versions are provided. If only one version, switch to logic-review.

Step 1. Identify the shared specification (guide Step 1) - what inputs should both versions handle; what outputs/side effects are expected. If the user states the refactor intentionally changed behavior in a specific area (e.g., "I changed the error path to raise instead of returning None"), record that as a declared spec change and treat divergences within that area as expected. Flag only divergences outside the declared change as findings.

Step 2. Build independent premises for each version (guide Step 2) - apply the Premises Construction Checklist to Version A and Version B separately.

Step 3. Trace both versions for the common case (guide Step 3) - parallel trace, same input, note the first divergence if any.

Step 4. Trace boundary cases (guide Step 4) - empty/null/zero, max/min, error inputs, first/last of collections. Start with at most three highest-risk boundary scenarios unless the user asks for exhaustive equivalence or the shared specification requires more.

Step 5. Identify and classify semantic divergences (guide Step 5) - each divergence is a finding with Premises → Trace → Divergence → Trigger → Remedy and an L-code.

Step 6. Equivalence verdict (guide Step 6) - one of: ✅ Semantically Equivalent, ⚠️ Conditionally Equivalent (state the condition precisely), ❌ Semantically Divergent.

Step 7. Output (guide Step 7) - Report Template with the Verdict header per common.md §5; localize headers if the user wrote in Chinese. Format is mandatory even for trivially short snippets: every divergence finding MUST use the five labeled fields (Premises / Trace / Divergence / Trigger / Remedy); never substitute with a plain paragraph or table.

Mode line in report: Semantic Diff (Chinese: 语义对比).

Limitations

  • Use this skill only when the task clearly matches its upstream source and local project context.
  • Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
  • Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

FAQ

Common questions

Discussion

Questions & comments · 0

Sign In Sign in to leave a comment.