The PR Description Problem: How One HTML Trick Makes AI-Written Code Reviews Readable Again

Reading Time: 4 minutes

AI coding agents like Claude Code write thorough but overwhelming pull request descriptions. Simon Willison's technique of collapsing the full AI-generated text inside an HTML details-summary block — with a human-curated opener visible by default — restores editorial trust without discarding any information.

The Problem With Pull Requests That Write Themselves

If you have handed off any coding work to Claude Code or similar AI agents recently, you have probably noticed something curious: the agent does not just write the code — it writes an essay about the code. The pull request description that comes out the other end is thorough, structured, and accurate. It describes the problem, the solution, and the verification steps in careful detail.

And yet, the moment you see it, your eyes glaze over.

Simon Willison, whose analysis of AI development tools is widely followed in the developer community, wrote about this exact frustration in a November 2026 post. Willison describes how most of the changes he makes to his projects now arrive as PRs opened by Claude Code or Codex, and how those PRs have a paradoxical quality: they are too good at describing the work. His words capture the feeling precisely — an agent-written PR description “reads like slop” even when every sentence in it is accurate and useful. The instant reaction, as Willison notes, is “I’m not reading all of that.”

This matters well beyond the world of professional software engineers. If you are a product manager in Pune reviewing code changes from a team that uses Claude Code, a startup founder in Bengaluru trying to track what your contracted developers have shipped, or a QA lead in Chennai who needs to sign off on feature branches — you encounter this wall of text too. And the wall does not get shorter just because the information inside it is good.

Why Length Signals Distrust, Not Quality

There is a psychological mechanism at work here that is worth naming. When a human writes a PR description, the length of that description is a signal of effort. A short, tight opening paragraph tells you that someone thought carefully about what matters. A three-paragraph preamble followed by a bulleted list of implementation choices tells you someone went deep.

When an AI writes a PR description, length is no longer a signal of anything except the agent’s tendency toward comprehensiveness. The model does not get tired. It does not feel social pressure to be concise. It has no reason to pick one detail over another, so it includes all of them. The result is text that is structurally indistinguishable from a thorough human write-up but reads as if no one curated it — because no one did.

Willison puts it simply: “I want human editorial judgement. I want someone to have thought just long enough about the PR to give me a human-approved introduction.”

That curation is what is missing, and it turns out you can restore it with a single HTML pattern.

The Fix: `

` in GitHub Markdown

The HTML

and

elements are a native browser feature that collapses a block of content behind a clickable heading. Click the heading and the full content expands. Leave it alone and you see only the summary line.

What Willison’s post highlights — and what many developers do not realise — is that GitHub’s Markdown renderer supports these tags directly inside issue comments and pull request descriptions. You do not need any special plugin or extension. You paste the tags into your PR body and GitHub renders the collapsed section automatically.

The structure Willison describes looks like this in practice:

• Opening paragraph: A short, human-written (or human-selected) introduction that gives readers everything they need to decide whether the PR deserves more of their attention. Sometimes a screenshot sits here too.
• block: The full agent-written description, collapsed by default. The summary line uses the model name and effort level — something like “Claude Opus 5.5 Medium” — so anyone who expands it knows immediately what generated the text.

The result, as Willison describes it: “My PRs don’t feel nearly as sloppy now. The information is all still there, but a reader can glance at it and get the top, human-curated information without their eyes glazing over.”

Nothing is hidden from the people who want the detail. Everything is hidden from the people who do not.

A Scenario From Bengaluru’s Tech Ecosystem

Consider a mid-sized fintech company in Bengaluru whose engineering team of eight developers uses Claude Code to accelerate feature delivery. The product manager — let us call her Ananya — reviews pull requests every morning to stay aligned with what is shipping. She is not a developer, but she understands the product deeply and is responsible for communicating changes to the business team and to external partners.

Before this pattern, Ananya’s mornings looked like this: open a PR, read four paragraphs of technical reasoning about why a particular API endpoint was refactored, skip to the bottom to find the one sentence that actually told her what changed for the user, and then write a Slack message summarising it herself. Multiply that by six PRs a day.

After the engineering team adopts the

pattern, each PR arrives with a one- or two-sentence opener that Ananya can read in fifteen seconds. If the opener raises a question — say, a change affects how transaction histories display for users on older Android versions — she expands the details block and reads the full Claude-generated analysis. If the opener is self-explanatory, she moves on.

The same information exists in both versions. The difference is that the new version respects her time and signals that a human stood behind the summary.

What This Pattern Cannot Do

It is worth being direct about the limits of this approach.

Remembering the Tag Order

One practical sticking point Willison flags is remembering whether the correct order is

or

. He offers two memory aids from his post.

The first is semantic: the

is where you summarise the

, so the

element must wrap everything, including the

. The summary sits inside the details.

The second is phonetic: say “details-summary” out loud. It flows as two syllables followed by three — a natural rhythm. “Summary-details” is three syllables followed by two, which feels like a stumble. Once you have said “details-summary” a few times, the order becomes automatic.

What to Watch For Next

This pattern is currently a manual convention, not a built-in tool. The next meaningful development to watch for is whether GitHub adds native Markdown editor support for the

pattern — something Willison explicitly hopes for in his post. If that happens, the barrier to adoption drops significantly and you can expect the convention to spread quickly among teams using AI coding agents.

For now, if your team regularly reviews AI-generated PRs and finds the volume of text discouraging, the pattern Willison describes is worth trying on your next branch. The investment is small: a one-paragraph opener you write or select yourself, and four lines of HTML wrapping the rest. The return is a PR that respects the reader’s time without discarding any of the information the agent worked hard to produce.