Collapse AI-Generated PR Descriptions with details/summary

When AI-Written PR Descriptions Are So Good You Don't Want to Read Them

Simon Willison recently shared a small trick: stuff the verbose AI-generated PR description into the HTML <details><summary> tag, keeping only a short human-written intro. On the surface it's a formatting gimmick, but underneath it touches a subtle psychological boundary in human-AI collaboration — when AI writes too completely, people lose the desire to read it.

According to his blog post, most code changes in his projects now come from PRs opened directly by Claude Code or Codex. These agents are quite good at writing PR descriptions: problem context, solution, verification steps — all present. But the problem lies precisely in being "too good."

"It's not necessarily slop, but it reads like slop!"

This comment points to a key distinction: the content may not be low-quality (slop usually refers to carelessly produced content), but its presentation — structured long paragraphs, exhaustive arguments, airtight heading hierarchies — immediately triggers the reader's defensive reflex of "this is AI-written, I don't want to read it all." Willison says that even when he himself is the one driving the PR, he instinctively resists reading it.

What Readers Want Is Editorial Judgment, Not Information Dumping

Willison's demand is clear: he wants human editorial judgment. Specifically, he needs an intro compressed by a human brain that explains at a high level what this PR does and whether it's worth investing more attention.

This actually reveals an easily overlooked collaboration gap: AI excels at generating complete information, but what human readers need is often not completeness but prioritization. What's important, what can be skipped, what needs careful reading — these judgments still rely on humans.

PR stands for Pull Request, the core collaboration mechanism of code hosting platforms like GitHub: after a developer completes changes on a branch, they request to merge the changes into the main branch via a PR, attaching a description of what changed, why, and how to verify it. The PR description is therefore both the entry point for code review and a vehicle for team communication. Before AI coding agents became widespread, PR descriptions were usually handwritten by the submitter, relatively short and focused; after agents like Claude Code and Codex automatically open PRs, the description text volume has expanded significantly, which is the direct source of the "reading defense reflex" problem mentioned in the article.

How the details/summary Collapse Approach Works

The solution is straightforward: use the <details><summary> tag supported by GitHub Markdown to collapse the long AI-generated description.

The HTML structure looks like this:

<details>
  <summary>Claude Opus 5.5</summary>
  <h2>The hook</h2>
  Plugins implement <code>register_agent_reference_types(datasette)</code>...
</details>

The key point: GitHub Markdown natively supports this tag. You can write it directly into a PR description or issue comment, and GitHub automatically collapses the content inside <details>, showing only the line of text in <summary> plus an expand arrow.

Willison's actual usage is:

1. Put a carefully chosen intro at the start of the PR as a high-level explanation — use the fewest words to help readers quickly get oriented.
2. Sometimes attach a screenshot, because images are often the best way to quickly show a new feature.
3. Stuff the complete AI-generated description entirely into <details><summary>.
4. Put the model name and effort level in <summary>, e.g., "Claude Opus 5.5 Medium," so readers can see at a glance where the collapsed content comes from.

Who Writes the Intro?

Interestingly, Willison doesn't always write the intro himself. Sometimes the agent has already produced what he needs within the large body of text, and he just picks it out and places it outside the collapsed section. But his commitment to readers is: this short intro represents his judgment as a human — ensuring the information here is worth the reader's time.

This pattern appears in several of his recent PRs:

• The intro to datasette PR #3052 explains why the row page was changed from a single-row table to a vertical field list — wide tables (such as the 46-column GitHub repos table) scroll off-screen horizontally, causing large blank areas on the page.
• The intro to datasette PR #3042 is straightforward: edit-tools.js (about 220KB) was previously loaded on every table, row, and database page, and now it's only loaded when the user interacts with editing features.
• The intro to llm PR #1838 uses one sentence to explain the command's purpose, followed by the --help output.

What these intros share: short, specific, judgment-driven. They are not summaries of the AI description but human-reorganized entry points.

<details> and <summary> are native HTML5 interactive disclosure elements, not a GitHub-specific extension. Browsers by default render <summary> as an always-visible header row (with an expand/collapse triangle), while the remaining child content is hidden in the collapsed state and expands on click, with no JavaScript required. GitHub's Markdown renderer allows inline raw HTML, so this element can be written directly into PR descriptions, issues, and comments. Note that Markdown nested inside <details> usually requires blank lines before and after the HTML block to be parsed correctly, and the collapsed state does not affect visibility logic for search engines or in-page find.

A Small Trick for Remembering the Tag Order

Willison admits he used to always forget the order of these two tags — whether it was <details><summary> or <summary><details>. He shares two methods:

The first is semantic: <summary> is clearly the line used to summarize the content, so it should be inside; <details> wraps everything else.

The second is more practical: always say this pair of tags as "details-summary". The rhythm of two syllables plus three syllables is smoother than the three-plus-two of "summary-details." Say it a few times and you won't mix them up again.

He also mentions one regret: he wishes GitHub would add a button in the Markdown editor to insert this pair of tags with one click. First, it would save the pain of typing manually on a phone keyboard; second, it would let more GitHub users know this feature exists.

A Transferable Collaboration Pattern

The value of this trick isn't limited to PR descriptions. It's essentially a progressive disclosure strategy: put the massive machine-generated details into an expandable container and keep the essence of human judgment on the outermost layer.

Today, as AI agents increasingly take on content generation tasks, readers' sensitivity to the "AI flavor" is also rising. Willison's approach suggests a direction: rather than making AI write more like a human, let humans retain the final editorial right and downgrade AI output to "optional in-depth reading material." This preserves the completeness of information while respecting the reader's attention budget.

He wrote at the end of his blog: "My PRs don't feel nearly as sloppy now!" — all the information is still there, but readers can glance at it and get the human-filtered core content, without staring blankly at several paragraphs of agent-generated details.

"Progressive disclosure" is a classic principle in interaction design and technical writing: present the most critical information first and expand details on demand to reduce cognitive load. It's common in advanced options in settings panels, collapsible examples in API documentation, and usability guidelines proposed by the Nielsen Norman Group. Willison's approach migrates this principle from interface design to collaborative text: AI handles generating the complete detail layer, humans handle distilling the summary layer, and readers decide for themselves how deep to go based on their attention budget. Compared with simply compressing the length of AI output, layering preserves information completeness while returning control over "how deep to read" to the reader.

One-line Summary

Collapse long AI-generated PR descriptions with details/summary, keeping only a short intro of human judgment.

Paragraph Summary

Simon Willison found that PR descriptions automatically generated by agents like Claude Code and Codex, while accurate and complete, trigger readers' "AI flavor" defense reflex due to their neat structure and exhaustive coverage, making people unwilling to read them through. His solution is to use the <details><summary> tag natively supported by GitHub Markdown to collapse the entire long AI-generated description, keeping only a short intro on the outermost layer that conveys human editorial judgment: what this PR does and whether it's worth a closer look. The intro can be excerpted from the agent's text but must represent human selection. The summary notes the model and effort level to indicate the source. The article also offers a trick for remembering the tag order and frames this as a transferable progressive-disclosure collaboration pattern.