UC-09: Compare Versions

When two refs, versions, or implementations need a rigorous behavioral comparison. Performs a bounded behavioral-equivalence check between side A and side B (side-effect diffs, exception-envelope diffs, and a dimension-by-dimension divergence matrix) and returns a structured verdict (equivalent, intentionally divergent, and so on).

What Makes It Different

  • It reconciles both implementations against the semantic model and produces a witnessed equivalence verdict with a divergence matrix, not an impression.
  • Ideal for refactor safety and for verifying that an AI-generated replacement preserves behavior.
  • It labels which dimensions diverge and which are preserved.

Prompt

Prompt
Run RubberDuck UC-09: Comparison.
[EDIT INPUTS ONLY]
target = <owner/repo or local path>
branch = auto
commit = latest
side_a = <current behavior / ref>
side_b = <diff / ref>
[/EDIT INPUTS ONLY]
Comparison only; do not edit repo. Required artifact: `COMPARISON_REPORT.md`.
Use prod RD to validate applied/current side: `get_started`, completed `detailed_repo_analysis(..., semantic_mode="full")`, Phase 2 ready, `load_code(max_files=4000)`, current-ref source/graph evidence.
Treat any supplied diff side as diff evidence, not applied code, unless the checkout is explicitly pinned to it.
Stop if either side, ref proof, hard RD gate, or hidden hard primitive after 3 scoped retries is missing.
Compare default behavior, compatibility, security invariant, remaining risky paths, exception/config drift, test adequacy, migration risk, and false assurance.
Write `COMPARISON_REPORT.md`: scenario, equivalence verdict, side-by-side table, divergence risks, compatibility tests, falsification steps, method notes.
Security artifact contract: include sections named Security Invariant, Adversarial Probes, Impact/Test Matrix, Evidence-Cleanliness Blockers, Unsupported Clean/Security-Ready Claims.
State whether sides are equivalent, intentionally divergent, or blocked; do not claim full safety beyond compared evidence.

Input

Repo, branch/ref, commit, side A, side B.

Output

A comparison report with a verdict and a per-dimension divergence matrix.

With RubberDuck MCP: Cross-Builder Comparison in ~11 Tool Calls

#Tool CallResult
1load_code(repo="local/sphinx", subpath="sphinx/builders", max_files=15)Multiple builder files loaded: HTML, Epub3, base Builder, gettext, dummy, etc.
2read_source(function_name="prepare_writing", analysis_id="init_5")Full 108-line HTML builder method (lines 428-535): search indexer, doc writer, global context
3read_source(function_name="prepare_writing", analysis_id="epub3")Full 8-line Epub3 method (lines 102-109): super() call + 4 context keys
4assess(mode="diff", analysis_id_before="init_5", analysis_id_after="epub3")Structural diff between the two builder files: symbol-level comparison
5search_code(pattern="def prepare_writing", analysis_id="all")5 implementations found across 52 analyses, with enclosing_function annotations
6query_action(action="shared_variables", analysis_id="init_5", params={method_a: "prepare_writing", method_b: "second-method"})Shared state analysis for HTML builder's prepare_writing
7query_action(action="call_chain", analysis_id="init_5", method="prepare_writing")24 callees verified: IndexBuilder, HTMLWriter, OptionParser, format_date, etc., coherence 1.0
8query_action(action="call_chain", analysis_id="epub3", method="prepare_writing")2 callees: super().prepare_writing() + THEME_WRITING_MODES.get()
9search_code(pattern="THEME_WRITING_MODES", analysis_id="all")2 matches: definition at line 45 and usage at line 106
10read_source(start_line=115, end_line=180, analysis_id="epub3")EpubBuilder base class: class attributes (copysource, embedded, search=False)
11read_source(function_name="build_update")Caller of prepare_writing: the build pipeline entry point

Side-by-Side Comparison

StandaloneHTMLBuilder (108 lines, 428-535)

def prepare_writing(self, docnames):
    # 1. Search indexer setup (conditional on self.search)
    # 2. HTMLWriter + OptionParser initialization
    # 3. Domain indices generation
    # 4. "Last updated" date formatting
    # 5. Logo/favicon URL handling
    # 6. Document relations collection
    # 7. Rellinks assembly
    # 8. Script/CSS file backup
    # 9. globalcontext dict creation (~30 keys)
    # 10. Theme options merge
    # 11. html_context merge

Epub3Builder (8 lines, 102-109)

def prepare_writing(self, docnames):
    super().prepare_writing(docnames)  # Gets all 108 lines above
    writing_mode = self.config.epub_writing_mode
    self.globalcontext['theme_writing_mode'] = THEME_WRITING_MODES.get(writing_mode)
    self.globalcontext['html_tag'] = self.html_tag
    self.globalcontext['use_meta_charset'] = self.use_meta_charset
    self.globalcontext['skip_ua_compatible'] = True

What Epub3 ADDS (4 keys to globalcontext)

KeyValuePurpose
theme_writing_mode'vertical-rl' or 'horizontal-tb'CSS writing-mode for Japanese/Chinese vertical text
html_tagEPUB3 namespace HTML tagxmlns:epub="http://www.idpf.org/2007/ops"
use_meta_charsetTrue<meta charset="utf-8"> for EPUB3 validation
skip_ua_compatibleTrueDisables IE compatibility meta (not needed in EPUB)

Call Chain Comparison (coherence 1.0 on both)

StandaloneHTMLBuilder.prepare_writing → 24 callees:
    IndexBuilder, HTMLWriter, OptionParser, load_indexer,
    format_date, _get_style_filename, collect_relations,
    isurl, basename, sorted, isinstance, bool, list, update...

Epub3Builder.prepare_writing → 2 callees:
    super().prepare_writing()  → delegates to all 24 above
    THEME_WRITING_MODES.get()  → dict lookup

All 5 Implementations Found via search_code(analysis_id="all")

BuilderFileLinesStrategy
Builder (base)__init__.py574Abstract: raise NotImplementedError
StandaloneHTMLBuilderhtml/__init__.py428-535Full implementation (108 lines)
Epub3Builderepub3.py102-109Extension via super() (8 lines)
TextBuildertext.py63Simple: creates TextWriter
I18nBuildergettext.py140Empty: return

Shared State Dependencies Mapped

StateCreated by HTMLUsed by Epub3?
self.indexerConditional on self.searchNo (EpubBuilder sets search = False)
self.docwriterHTMLWriter(self)Yes (inherited)
self.docsettingsOptionParserYes (inherited)
self.domain_indicesGenerated from domainsYes (inherited)
self.globalcontextDict with ~30 keysExtended with 4 EPUB3 keys
self.relationsenv.collect_relations()Yes (inherited)

Without RubberDuck MCP: Same Conclusion, More Manual Work

The AI read both files, grep for def prepare_writing across the codebase, read each builder file individually, and manually compared implementations.

GapDetail
No verified call chainListed what prepare_writing "probably calls" based on reading, no formal dependency count. MCP's call_chain action returned 24 verified callees with coherence 1.0.
No structural diffCompared implementations by reading both, no symbol-level structural comparison. MCP's assess(mode="diff") provided a formal structural diff.
No shared state verificationDescribed shared state from reading: "globalcontext is shared." MCP's shared_variables + call_chain formally mapped which state HTML creates, which Epub3 inherits.
No THEME_WRITING_MODES tracingMentioned the constant but didn't verify where it's defined. MCP's search_code found both the definition (line 45) and usage (line 106) in one call.

Comparison Table

DimensionWith RubberDuck MCPWithout MCP
Implementations found5 across 52 analyses: 1 search call6 across builder files: 6+ file reads
Call chain (HTML)24 callees, coherence 1.0"It calls IndexBuilder, HTMLWriter, etc.", reading-based
Call chain (Epub3)2 callees, coherence 1.0"It calls super() and adds 4 keys", correct but unverified
Structural diffassess(mode="diff"): symbol-levelManual reading of both files
Shared stateFormally mapped: 6 attributes with create/inherit/extend statusProse description: "globalcontext is shared"
Constant tracingsearch_code found definition + usage in 1 callMentioned but not traced

Bottom line: Both approaches correctly compare the two implementations and identify Epub3's 4 additions. But MCP's analysis is formally verified: call chains carry coherence 1.0, structural diffs are symbol-level, shared state is mapped with create/inherit/extend status.

Videos

With RubberDuck MCP

Same Sphinx repo, now comparing prepare_writing across StandaloneHTMLBuilder and Epub3Builder with both RubberDuck MCP servers enabled in Cursor. The agent calls load_repo, read_source, compare_snapshots, search_code, shared_variables, and call_chain directly against the semantic graph, and search_code alone surfaces all 5 implementations across 52 analyses in a single call. call_chain returns 24 verified callees for the HTML builder and 2 for Epub3, both at coherence 1.0, so the final verdict (Overall Risk LOW, no breaking changes, key collisions unlikely because EPUB3's keys are namespaced) rests on a formally traced call graph and shared state map, not a guess.

Without MCP

Same repo, same prompt, both MCP servers disabled in Cursor Settings. With no semantic tools to call, the agent launches a subagent that reads epub3.py by hand (lines 1 to 105) and greps for constants like html_tag, use_meta_charset, and THEME_WRITING_MODES to work out what Epub3Builder adds. It reaches a similar conclusion, a shared state table and a list of 7 builder implementations including TextBuilder and XMLBuilder that the MCP run never surfaced, but every dependency in it (self.docwriter, self.domain_indices, and the rest) is inferred from reading source, not verified against a call graph or a coherence score.