Episode 07 --- Semantic Diff
Working YouTube title:
A Diff That Knows What a Rename Is
Thumbnail thought:
git sees delete + add. muse sees a rename.
Target runtime: ~7:30
[0:00--0:20] COLD OPEN
[CAMERA --- Episode 06's closing question, on screen: "what does a diff look like on something that actually has interesting structure?"]
GABRIEL:
Let's find out. Real code, real refactors, no todo lists this time.
[TITLE CARD --- fast]
SEMANTIC DIFF
[Music enters.]
[0:20--1:00] THE BASELINE
[TERMINAL]
$ cat calc.py
def add(a, b):
return a + b
def subtract(a, b):
return a - b
GABRIEL VO:
Two functions. Nothing fancy. We're going to do three ordinary things to this file and watch what Muse actually notices each time.
[1:00--1:50] RENAME
[TERMINAL --- edit add to sum_values, nothing else changes]
$ muse commit -m "Rename add to sum_values"
$ muse diff HEAD~1 HEAD
[SCREEN --- real, unedited CLI output]
M calc.py
└─ renamed to sum_values
1 modified file, 1 modified symbol
GABRIEL:
I didn't run a special rename command. I edited one line and committed like normal.
[beat]
Muse compared the function's body before and after, saw they matched, and concluded the only thing that changed was the name. Not "three lines deleted, three lines added." A rename.
[1:50--2:30] THE BREAKING CHANGE CALL
[SCREEN --- the full structured delta]
{
"old_summary": "function add",
"new_summary": "renamed to sum_values",
"sem_ver_bump": "minor",
"breaking_changes": ["calc.py::add"]
}
GABRIEL VO:
It went further than naming the rename. It classified the impact:
minor version bump, and anyone calling add by name just had their
code broken.
[beat]
That's not a text observation. That's an opinion about your public API, computed from a rename Muse detected on its own.
[2:30--3:15] MOVE ACROSS FILES
[TERMINAL --- move subtract into a new file, extra.py]
$ muse commit -m "Move subtract to extra.py"
$ muse diff HEAD~1 HEAD
[SCREEN --- real output]
A extra.py
└─ added function subtract ← moved from calc.py
M calc.py
└─ removed function subtract → moved to extra.py
2 modified files, 1 added, 1 removed symbols
GABRIEL:
Two files changed. One function. Muse tells you they're the same event, in both directions, automatically.
[3:15--3:50] WHAT GIT WOULD HAVE SHOWN INSTEAD
[SCREEN --- callback to Episode 00's Git segment]
GABRIEL VO:
Git sees this exact change as two, unrelated facts: a file lost three lines, a different file gained three lines.
[beat]
No connection between them, because Git's model of the world stops at lines. It was never going to see the move --- not because Git is bad at diffing, but because "this function relocated" isn't a sentence Git's model can even express.
[3:50--4:30] THE CONTROL CASE --- REORDERING
[TERMINAL --- swap the order of two functions in a file, nothing else changes]
$ muse commit -m "Reorder helper_a and helper_b"
$ muse diff HEAD~1 HEAD
M extra.py
1 modified file
GABRIEL:
No symbols listed. Zero.
[beat]
The file's bytes changed --- moving text around a file always changes its bytes --- so Muse is honest that the file itself is different. But it looked inside, found the exact same two functions, unchanged, just reordered, and reported nothing at the symbol level worth naming.
[SCREEN --- the actual stored summary string]
"extra.py (reformatted — no semantic change)"
That's not paraphrased. That's the literal string Muse wrote down.
[4:30--5:10] THE CAPSTONE --- DETECT-REFACTOR
[TERMINAL]
$ muse code detect-refactor
[SCREEN --- real output, full history]
MOVE calc.py::subtract → extra.py
RENAME calc.py::add → sum_values
2 refactoring operation(s) detected
(1 move · 1 rename)
GABRIEL VO:
One command, walking the whole commit range, correctly labeling both events by kind --- not "here are some diffs, you figure out what happened." Muse already knows what happened.
[5:10--5:50] THIS ISN'T CODE-SPECIFIC MAGIC
[CAMERA]
Nothing about this is a special code-domain trick bolted onto Muse.
[beat]
Episode 05: diff() is one of the six methods, and every domain
implements it in its own terms. Episode 06: our todo plugin's diff()
did the exact same job for tasks --- "this task was added," "this task
was removed" --- using the same address-keyed reasoning, just simpler,
because a todo list has less structure to reason about than a
codebase.
[CAMERA]
Code just happens to have enough internal structure --- symbols, call
graphs, identity that survives a rename --- for diff() to say
something this specific.
[5:50--6:25] THE POINT
[CAMERA]
A diff is supposed to answer "what changed." Most tools answer that question by telling you which bytes moved.
[beat]
That was never actually the question anyone was asking.
[ON SCREEN]
A DIFF IS A CLAIM ABOUT MEANING, NOT A REPORT ABOUT BYTES.
[6:25--7:00] OUT
[TERMINAL --- Episode 01's clean merge, one more time]
GABRIEL VO:
We've now watched Muse understand a change. We haven't asked how it uses that understanding to reconcile two people's changes into one.
[beat]
Next episode: the merge engine, properly. What actually happens underneath a merge that never shows you a conflict marker.
[CAMERA.]
[CUT TO BLACK]
musehub.ai
Production Notes
Episode 07 is a three-beat magic trick, structured on purpose: rename, move, then a control case that proves the first two weren't a fluke of lenient pattern-matching. The control case is not optional --- a technical audience's first objection to "look, it detected a rename" is always "sure, but does it also cry wolf on ordinary changes," and the reorder example answers that before anyone gets to ask it.
Opening
Answer Episode 06's question directly: "real code, real refactors." Skip any recap of what a diff is conceptually --- the audience has watched six episodes of real diff output already. Go straight to the two-function baseline file.
Don't Overclaim the Reorder Case
While researching this episode, the reorder commit's structured delta
also carried a sem_ver_bump and a breaking_changes entry despite
its own summary text explicitly saying "no semantic change" --- an
inconsistency between the diff's own child-level description and the
semver classifier's file-level fallback, not something fully
understood yet. The episode deliberately shows only the symbol-count
and the summary string for this beat, and never mentions semver bump
for the reorder case. If this gets root-caused before recording, it's
worth a one-line update; if not, the omission is correct as scripted
--- never state a claim on screen that couldn't be verified cleanly.
Every Claim Gets Real Output, Same as Every Episode Before This One
Rename, move, and reorder are all real muse diff/muse code detect-refactor output against an actual sequence of commits, run for
real before scripting the beat. Re-verify against whatever muse
build is current at record time before shooting.
Tie Back to Episode 06, Explicitly
The "this isn't code-specific magic" beat is the episode's real
thesis and should not be rushed or treated as a footnote. Say plainly
that the todo domain's diff() did the same kind of work with less
structure to work with --- this is what keeps the season's six-method
claim honest three episodes after it was introduced.
The Seed
The viewer arrives thinking:
Okay, that's a genuinely nice diff. But diffing is the easy half of version control.
They should leave thinking:
If the diff already knows this much about what changed... how much of "merge" does it get for free?
That's Episode 08, and it should open by taking that question seriously rather than answering it right away.