A Better Way to Review Code

It’s no surprise at all that we live in a very interesting time of technology. AI (LLMs) have revolutionized what people can do and accomplish in a way that we haven’t really seen since the introduction of modern IDEs. I have what I think is a healthy amount of excitement and doubts about AI which I will cover in another post, but I wanted to show off something that I built in tandem with AI over the weekend. Not just vibe coding — but pairing my 15 years of experience as an engineer and people leader with AI to actually build something useful. While AI has transformed how we code, we’re still stuck with code reviews that haven’t meaningfully evolved in over a decade.

The problem — Code Reviews haven’t really changed drastically in a long time. In most cases that isn’t a problem. I am a huge believer of “if it’s not broke…”. The problem is we have all written (it’s a safe place you can admit it here) and reviewed a Pull Request that was for lack of a better words… a mess. There are many types of bad PRs out there here are few types you probably encountered in the wild:

The Mammoth Merge

You open the PR and it hits you: “256 files changed”. There’s no summary — just a title like “Refactor + Feature work”. Somewhere in that haystack is a new API endpoint, a full frontend redesign, and a few unrelated bug fixes that should’ve been their own branches.

The result? Review paralysis. You either rubber-stamp it to avoid being a blocker, or lose half your day trying to unravel it.

The One-File Wonder with Hidden Depths

At first glance, it’s small. One file. A hundred lines. Easy. But then you notice it rewrites payment logic, subtly changes error-handling, and deprecates a shared utility.

The description? “Refactor for clarity.”

Now you’re left guessing whether you just approved a time bomb.

The Mysterious Refactor

“Just cleaning up some code,” the description says. But the diff shows renamed methods, restructured logic, and modified interfaces. It’s technically correct — nothing’s broken — but everything’s different.

And without context, you’re stuck deciding: do I trust the author’s gut, or leave a dozen comments trying to reverse-engineer the intent?

The Feedback Whiplash PR

You leave thoughtful feedback. The author replies with “good point,” and pushes a totally different change. Then another. Then another. Now your comments are obsolete and the PR is a moving target.

It’s hard to tell if your input was helpful or ignored — but you do know one thing: you don’t want to review this one again.

Introducing Code Story

Code Story began as an idea a few years ago, with the core goal of improving code reviews and pull requests. It stemmed from frequent feedback I give to engineers: "Code reviews aren't just about getting feedback on your work—they're often the first time a reviewer sees your code, architecture, and ideas. They're learning how the codebase will evolve and change. They are both a place for feedback and a place for education." This perspective came from witnessing various review patterns throughout my career: the epidemic of rubber-stamping large PRs, reviews becoming competitive arenas for engineers to show off their expertise, and occasionally, reviews done perfectly—with carefully crafted descriptions and helpful comments that guide reviewers through the changes like breadcrumbs. The fundamental problem? Current tools don't support building a narrative around changes. And even if they did, would developers invest time in writing meaningful explanations? That's why now feels like the perfect moment to build Code Story. After two decades of tooling improvements, we're ready for what I believe will be the next evolution in code reviews.

What is Code Story?

Code Story is a platform that works alongside your current version control system (starting with GitHub). It enables you to build a Story linked to your PR that facilitates meaningful feedback and discussion around your code changes. Think of it as your favorite blog editor—but with the power to inject code diffs, metrics, bugs, and anything else that helps build the narrative of your changes.

After onboarding, you can select any of your PRs and generate a Story from them. You can let AI take a first pass at pre-filling your Story, which reduces the time needed to create meaningful information for your teammates. Or, if you prefer, you can start from scratch.

This opens a blank canvas where you can curate how others understand your changes. You control the narrative flow by arranging code diffs in a logical sequence, helping reviewers grasp the full context of your updates.

The Code Story editor tracks how many PR changes you've included in your Story and features blogging capabilities for tagging and grouping Stories (with AI-powered organization coming soon). A particularly useful feature is how it identifies Subject Matter Experts (SMEs) based on their contributions to specific areas over time. While teams can manually curate these SME groups, the system also automatically generates them by analyzing code and Stories that people create and engage with.

Visualizing a story is like reading a blog, with the narrative flowing from top to bottom. It begins with our Code Story Score Card, which gives readers a clear preview of what's ahead. You can highlight interesting sections for later reference and add comments to the Story. Unlike traditional code reviews where comments are scattered across multiple files without context, here they're consolidated in one place.

Future of Code Story

Code Story has incredible potential. In today's world of remote software engineering with globally distributed teams, it can become a powerful platform for engineers to exchange meaningful feedback and foster continuous learning. One particularly valuable application is how it can aggregate feedback from Stories to track improvement in engineering skills, communication abilities, and idea presentation. Unlike the current landscape where metrics drive everything but engineers receive little actionable feedback—typically just a vague collection of accomplishments and areas for improvement every 6-12 months—Code Story offers a more immediate and practical approach.

Code Story could also serve as comprehensive documentation for teams. By replacing traditional PRs with Stories and organizing them carefully for future reference—like a digital library—teams can build an invaluable knowledge base. Moreover, Code Stories have the potential to become the central hub for understanding code evolution and could even replace traditional Architectural Design Reviews.

Be the first team to re-write their Story

All of the cool things that Code Story could become is locked behind the first team to take a leap. I’m looking for a team willing to take the first step — to make code feel more like a conversation and less like a checklist.

If you’re tired of “LGTM” being the peak of collaboration, and you want your code reviews to actually mean something — I’d love to build it together.