While talking with an LLM, a question occurred to me.

What if the human brain is not particularly well suited to understanding complex things through prose?

Reading prose is harder than it looks

When I write code, something like a flowchart appears in my head. Processing branches on conditions, merges somewhere, and continues to the next operation.

Design feels a little different. What I have in mind is closer to a data-flow diagram. I think about where data comes from, which modules it passes through, and how it is transformed. When I work on infrastructure, I am almost certainly thinking about the flow of data too.

In other words, when I program, what is in my head is not prose.

But when I explain it to someone else, it becomes prose. My questions to an LLM are prose, and the answers from the LLM are usually prose as well. I convert the structure in my head into sentences, then the person receiving those sentences reconstructs the structure in their own head. That feels unnecessarily roundabout.

GitHub pull requests have the same problem. Open a PR and you see a list of code diffs. The diff is important, of course, but reading it from top to bottom does not always reveal the whole change. You have to move between several files and reconstruct how they connect in your head.

Reading code and understanding a code change are not necessarily the same thing.

Start with a diagram, then use prose for the details

My personal sense is that, when encountering a mechanism for the first time, video is easiest to enter through, followed by audio and then prose.

That order does not apply to every kind of information. Prose is often better for checking precise conditions, numbers, and fine details. But to grasp a system’s overall structure or the path that data takes, looking at a diagram is often faster than reading paragraphs of explanation.

If so, perhaps there is no need to explain everything in prose from the beginning.

Show the overall architecture first. Use a data-flow diagram when the movement of data matters, a sequence diagram when ordering matters, or a state diagram when state changes matter. Then use prose to explain why the design was chosen, its tradeoffs, and the detailed behavior.

There is no need to explain in prose what a diagram already makes clear.

Conversely, there is no reason to force information into a diagram when prose can express it more accurately. The medium should fit the information.

This also seems like work that LLMs should be good at. An LLM can read source code and documentation and explain what they mean. Instead of producing that explanation as a long block of prose, it could turn its understanding into diagrams.

For code review in particular, seeing the before-and-after structure or data flow before reading the diff might make the overall change easier to grasp. That was the idea.

I built Ruyka

So I built Ruyka, a Claude Code skill that turns a GitHub pull request into an explainer page where diagrams take the lead and prose plays a supporting role.

Its basic use is simple: give Claude Code a pull request URL.

/ruyka https://github.com/owner/repo/pull/123

It also accepts owner/repo#123, or just a PR number when the current directory is the relevant repository. Ruyka uses the gh CLI to retrieve the PR description, linked issues, commits, complete file list, and diff. If the diff does not provide enough context, it reads the surrounding code as well. It then chooses diagrams suited to the PR and creates an explainer page.

The page is stored as a private Artifact in your own account, and Ruyka returns its link when finished. Running it again for the same PR overwrites the existing page while keeping the same URL.

It requires Claude Code with access to the Artifact tool and a logged-in gh CLI that can read the target repository. Installation instructions are in the Ruyka README.

The first diagram should explain the change

Ruyka always starts with a diagram called “At a Glance.” That diagram should be enough to understand what the PR changes and what differs before and after.

It chooses any later diagrams according to the nature of the PR. A change to an API path might call for a sequence diagram; a stateful process for a state diagram; a module split for a dependency graph; a database change for a data model; and a change spanning many modules for a change map.

Ruyka generally selects two to five diagrams, but one or two are enough for a small PR touching only one or two files. It does not add diagrams merely to reach a quota.

Beside each diagram, prose explains the reason for the change, design tradeoffs, and the files or functions reviewers should inspect. At the end of the page, a table maps changed files to the corresponding diagrams, followed by concrete review points. The reader can understand the outline first, then descend into the actual diff.

A collection of boxes is not enough

The goal was never to maximize the number of diagrams.

When diagramming becomes the objective, the result is often just a set of boxes labeled with filenames. That merely replaces prose with shapes; it does not make the change easier to understand. If a constant changed from 30 to 60, one sentence is more useful than another diagram.

Ruyka focuses on what a reader will understand after seeing a diagram. Each diagram makes one claim, and arrows carry labels such as “calls” or “writes” that state the relationship. It does not invent architecture that cannot be supported by the diff, and any unsupported inference must be labeled as such.

The goal is for a reviewer to spend two or three minutes on the page and come away knowing the outline of the change and where to focus.

Whether diagrams actually shorten review time or reduce missed problems still needs to be tested. Nor is an LLM-generated diagram guaranteed to be correct. A clearly drawn but incorrect relationship may be more misleading than prose. Reviewers still need to inspect the original code and diff.

Even so, I think there is value in seeing the whole change before reading through the diff.