Every developer has hit this. You open a project months later, stare at a commit that says "Refactor cache layer," and think... why did I do that? The diff shows you what changed, every line. It never tells you why you changed it.
That missing "why" is the thing I've been building Alpheon to fix, a tiny tool that reads your git diff and writes a handoff note. The free version fills in a template you write yourself. But I wanted to answer a harder question: could a model reconstruct the reasoning on its own, from the diff alone, without making things up?
So I stress-tested it. Here's what I learned.
The rule that matters more than the model
Before any of the results, this is the part I care about most. A tool that confidently invents a reason is worse than no tool, because now a wrong "why" is written down as if it were true, and the next person believes it.
So the instructions to the model are strict:
- Base every claim on evidence in the diff. Never invent tickets, users, or motivations.
- When you're inferring, say "likely" or "appears to." A hedged real reason beats a confident guess.
- Reference actual code symbols and values so the reasoning stays grounded.
- Don't just restate the commit message. Reason from the code itself.
- Everything below lives or dies by whether the model actually respects those rules under pressure.
A real example
Take a commit whose message is just "Prevent stall when cache is full." The diff is small, a deposit path that used to write unconditionally now checks for overflow first. Here's what the tool produced:
"The change prevents the writer from stalling when the cache is full. The original code kept trying to write entries even when they could not be fully accepted, which could trap it in a loop against a full store. The path now measures capacity before and after, computes any overflow, and clears the pending entry regardless, so the writer is freed to continue.
Tried and rejected: The diff replaces an unconditional write with an overflow-aware one, which suggests the earlier straight write was the approach that caused the stall and was dropped."
That's not a paraphrase of the commit message. It read the code, identified the actual failure (the stall loop), and inferred what the old broken approach must have been. That's exactly the reasoning that normally evaporates the moment the session ends.
Stress-testing it honestly
One good example proves nothing, anyone can cherry-pick. So I ran it across a batch of commits from a real, messy codebase: everything from one-line fixes to a single refactor over 40,000 characters long. Terse commit messages, no docs to lean on, the worst-case conditions for recovering intent.
I graded every result by hand. I'm not going to pretend it was flawless, because the whole point is honesty:
Most: accurate. Real reasoning, grounded in the diff, correctly hedged where uncertain.
A few: plausible. On changes where the motivation genuinely wasn't visible in the code (a camera-bounds tweak, for instance), it played safe and mostly described the change. Not wrong, just thin.
Zero: hallucinated. Not one invented reason across the whole batch, including the 40k-character refactor big enough to choke on.
That last line is the one I lose sleep over, and the one that made me trust it. The failure mode of these tools isn't vagueness, it's being confidently wrong. Getting zero fabricated reasons across a brutal test set is the result worth reporting.
Why it runs locally, not on someone else's API
People ask this, so: the model runs on a GPU I control, not a third-party API. Your code never gets shipped off to OpenAI or anyone else. For a tool whose entire job is reading your private diffs, that felt non-negotiable.
Try it on your own forgotten repo
Here's the fun part. Go find the project whose commits stopped making sense to you, and see what the "why" actually was.
The core tool is open source, MIT, single file, zero dependencies:
github.com/BravoAlphaSix/alpheon
If the idea resonates, a star genuinely helps, it's how the next person fighting the "lost why" problem finds it. And if you run it on something and the result surprises you, good or bad, tell me in the comments. I'm building in the open, and the failure cases are the most useful thing you can hand me.
Top comments (0)