Back to Explore
NewsVibeFix editorialUpdated Nov 17, 2026

Simon Willison's New Habit: Hide AI-Written PR Descriptions Behind a Details Block, Keep One Human Sentence

On 9 November 2026, Simon Willison shared a small habit: each PR opens with one short human-approved sentence, while the agent's full write-up sits inside a native GitHub <details><summary> block labelled with the model name and effort level. Nothing is lost, yet reviewers no longer get scared off by the wall of text. Five real PRs already use it, and the template is copy-ready.

Screenshot from Simon Willison's blog post: a GitHub PR page with his short human-written opener on top and a collapsed, clickable 'Claude Opus 5.5' heading below it.

On 9 November 2026, Simon Willison shared a small working habit on his blog: he has started hiding AI-generated PR descriptions inside HTML

blocks, leaving only a short, human-approved opener at the top of each pull request. No new tool, no new process, no money spent — just a native feature GitHub Markdown has supported for years. Yet it hits a pain point that keeps growing: AI now writes PR descriptions so well that nobody wants to read them.

Screenshot from Simon Willison's blog post: a GitHub PR page with his short human-written opener on top and a collapsed, clickable 'Claude Opus 5.5' heading below it.

The verdict first: the problem is not that AI writes badly, but that it writes too much

Willison's situation is representative. He says most changes to his projects now arrive as pull requests opened for him by Claude Code or Codex. The PR is his unit of work: he uses it to bundle commits together, iterate until a feature is complete, document decisions, and then merge the finished result. And today's coding agents are great at writing PR descriptions. They are accurate and comprehensive, covering the problem, the detailed solution, and the steps taken to verify it. That should be a good thing.

But Willison's judgement is blunt: the problem is exactly that they are too good. An agent-written PR description easily runs to several well-structured paragraphs, complete with headings, lists, and code references. Nothing in it is wrong — it is just exhausting to read. His own words are frank: it is not necessarily slop, but it reads like slop. The moment you recognize a piece of writing as AI-generated, your first reaction is "I'm not reading all of that." No matter how accurate or useful the information is, the sheer length puts you off before you start — reading it feels like it would take longer than it took the driving author to write it, even when that driving author is you.

This judgement deserves to be taken seriously, because it names a truth that is easy to miss: the first job of a PR description is not to record, but to persuade — to persuade a reviewer to keep reading. However complete the writing is, if the opening drives people away, everything after it might as well not exist. The problem with AI writing here is not quality but length and pacing: it does not know when to stop, and it does not know what the reader most needs to know first. It lays every fact flat in front of you, and pushes the entire cost of filtering onto the reader.

What Willison wants is equally clear: human editorial judgement. He wants someone — even someone who spends only a moment thinking — to distill the PR into one human sentence first: what this change is for, and whether it deserves more of your attention. Not a longer summary, but a shorter judgement. With that opener in place, the reader can decide: is this one sentence enough, or is it worth clicking to read the whole thing?

The method: three sentences explain the whole trick

The method itself is simple enough to state in one sentence: keep only a short, human-selected, high-level explanation at the top of the PR description; put the agent's full essay inside a

block; and use the model name and effort level — "Claude Opus 5.5 Medium", for example — as the summary line. Three sentences, and that is all of it.

Willison shows what it looks like in his post. The top of the PR is a short passage he has picked out, sometimes with a screenshot, since images are often the fastest way to show a new feature. Right below it comes the collapsed block: a

tag wrapping the entire agent-written text, with a tag holding just the model name. Once rendered, the reader first sees a short, clear human opener, followed by a line with a small triangle arrow reading "Claude Opus 5.5". Click it, and the full text expands. Before you click, the whole PR looks as tidy as if a human had written it.

Two details here show real craft. First, he does not always write the opener himself. Sometimes the agent has already produced the sentence he needs, buried somewhere in the avalanche of other text — all he has to do is pick it out and move it to the top. In other words, he has not added much work; he has swapped writing for selecting. The cost of that judgement is low, but its value is high. Second, the summary line is not decoration, it is honest labelling. Readers can see at a glance which model wrote the text below, and at what effort level. That is decent transparency: the AI-written text is neither hidden away and passed off as human writing, nor deleted and pretended away. It is simply put in its proper place.

Willison says his PRs don't feel nearly as sloppy now. Not a word of information is lost, but a reader can glance at the top, get the human-curated point, and move on without their eyes glazing over at multiple paragraphs of agent-written detail. That change in experience comes not from any deep technology, but from a simple layout decision: the important thing first, the detail afterwards, and whoever wants it can click to open it.

Five real examples: this is not theory, it is already his workflow

Willison does not just argue the case; he links five real pull requests where he has already used this pattern, all from his own projects, so readers can click through and check each one. That matters: a working habit is worth copying first of all if the person proposing it actually uses it themselves.

The first is Datasette PR #3052, redesigning the row page as a vertical list of fields. The opener is a single human sentence: the row page used to show its single row as a one-row table, which for wide tables scrolled far off to the right and left most of the page blank — followed by a screenshot. How exactly it was rebuilt, how each field's copy button and empty-value styling works, all of that sits inside the collapsed block. The PR was merged on 8 November 2026, and you can still open it on GitHub today and see that short opener at the top.

The second is Datasette PR #3043, adding a pagination bar that shows which rows are on the current page. The opener, in one sentence: table pages spanning more than one page now make it obvious where you are, with navigation at the top as well as the bottom. The third is PR #3042, loading edit-tools.js on demand. That roughly 220KB script used to load on every table, row, and database page, even for users who could not edit anything; now it only loads for users who can edit, when they first interact with an edit feature. The opener states the waste and the fix, and the trigger conditions and details stay folded away.

The fourth is datasette-agent PR #51, adding a register_agent_reference_types plugin hook so plugins can add their own kinds of item to the hash-tagging in the chat composer. The fifth is llm PR #1838, adding llm openai endpoint add, list, remove, and path commands, so OpenAI-compatible endpoints can be saved from the command line instead of by hand-editing YAML. The five examples span UI redesigns, performance work, a plugin mechanism, and CLI tooling, which shows the pattern is general, not tied to one kind of change.

Notably, none of these five changes is trivial — one of them adds an architecture-level plugin hook. Yet Willison leaves each PR with an opener of only one or two sentences. That restraint is deliberate: the opener is not a summary, it is a judgement — a judgement about what the reader most needs to know first. A summary shortens the full text; a judgement decides the reading order. They look similar, but the effect is very different.

Why details and summary, of all things

The whole trick rests on one precondition: GitHub Markdown natively supports

and . You can drop those two HTML tags straight into a PR description or an issue comment, and GitHub renders them as a collapsed section with an expansion arrow, showing just the summary line. Inside the block you can put headings, text, images, and code blocks — nothing is missing. GitHub's own documentation has a page on exactly this feature, called "Organizing information with collapsed sections", and it even notes that adding the open attribute makes the section display expanded by default.

In other words, Willison invented nothing. He simply took a feature that has existed for years, but that many people do not know about or forget to use, and placed it exactly where it is needed. The clever part is that it costs nothing: no plugin to install, no workflow to change, no new GitHub feature to wait for. Anyone can use it the moment they open a PR edit box, and the whole team can learn it tomorrow.

Compare that with the heavier responses to AI writing flooding in. Some propose detection tools that score AI content; some want to add a human rewrite step to the process; some simply ban AI-written descriptions outright. Those approaches add tooling cost, or labour cost, or fight against reality — agents are already writing, and they keep getting better at it, so blocking them is a losing battle. Willison's approach sidesteps all of that confrontation: don't block it, don't delete it, don't rewrite it — just move it. The AI keeps writing the long text it is good at, and humans only add one sentence of judgement at the top. The division of labour stays the same; the reading experience changes.

There is another advantage that is easy to overlook: the approach is honest with readers. Labelling the folded block with the model name leaves a clear provenance in the PR — human judgement above, AI-written text below. Readers are not misled, and they do not discover halfway through that the passage they are reading was written by a model. As AI-generated content keeps growing, that kind of labelling is itself a form of trust-building.

What makes it work: nothing is lost, but the burden is halved

The easiest way to misunderstand this trick is to think it hides things. It does not. The folded content has not disappeared and has not been downgraded; anyone can see the full text with one click, and search still finds it. For reviewers who genuinely need the detail — someone picking up this code next, or re-checking the verification steps — the information stays exactly where it was. What the trick compresses is not the amount of information, but the amount you see at first glance.

That is precisely why it works. It accepts a simple reality: different readers need different things from the same PR description. A passing colleague only needs to know what the PR is for; the maintainer merging it needs to know whether the change is safe; your future self needs to know why it was done this way. One flat, sprawling essay tries to serve all of them at once, and ends up tiring everyone. Willison's layered approach lets each reader take what they need: read the opener and leave, or click open and dig into the full text.

At a deeper level, the trick repairs a rhythm mismatch between AI writing and human reading. Writing costs an AI almost nothing — it can produce thousands of words in one breath. Human attention, on the other hand, is scarce: you open a page, scan it, and only continue if it seems worth it. In the past, humans wrote for humans, so length was naturally limited by the author's stamina. Now AI writes for humans, and length has lost its natural brake. Willison's collapsed block puts a brake back on AI's length — not by limiting what it writes, but by limiting what it shows first.

For vibe coding practitioners, this is especially worth thinking about. Many people's workflow now looks just like Willison's: Claude Code or Codex changes the code and opens the PR, while the human reviews and merges. The PR description is the most easily neglected link in that pipeline — the code gets reviewed line by line, while the description is waved through untouched. The result is PR descriptions in a repo that grow longer, more uniform, and less likely to be opened at all. Willison's approach adds a lightweight human checkpoint to the pipeline: before merging, think clearly for one sentence — what is this PR actually for? If you cannot answer that, your understanding of the change is not solid enough yet, and no collapsed block will save you.

Before you copy it: four boundaries to think through

Good as this trick is, it is not a cure-all. Before copying it, four boundaries are worth thinking through, or it is easy to use it in the wrong way.

First, collapsing is not cover-up. If the agent's description is itself poor — facts wrong, logic muddled, verification steps invented — folding it away does not fix the problem, it just hides the problem one click deep. Willison's approach works because the agent's text is accurate and comprehensive, and only lacks a human opener. If your agent often writes wrong things, fix the prompts and the workflow first; don't expect a collapsed block to do that job. Folding can solve "too long". It cannot solve "too wrong".

Second, folded content goes stale. A PR changes through review rounds, and the code moves while the description does not always follow. A flat essay at least shows the mismatch at a glance; a folded essay is easier to overlook, and can end up as an archive that no longer matches the final code. Willison's five examples are all small, fast-merged PRs, where drift is a minor risk. If your PR goes through many review rounds with large changes, re-read the folded text before merging — or say plainly in the human opener that the description reflects the latest commit.

Third, don't fold away the things that genuinely matter. The human opener should carry anything a reviewer must know: breaking changes, security impact, migration costs. Those belong outside the fold. The folded block is for the "read more if you want" detail, not for content you hope nobody sees. Using it to hide risk notes or known issues is dishonest to reviewers and careless with your own repo. Willison's opener is trustworthy precisely because he makes a promise: the short opener represents his human judgement about what is definitely worth the reader's time. Once that promise is abused, the whole trick stops working.

Fourth, there is still a little operational friction. Willison ends his post with a wish of his own: he hopes GitHub will add a button to its Markdown editor for this, partly to save him painstakingly typing the tags on his mobile keyboard, and partly to spread the word that the feature exists. For now, the trick depends on hand-typing HTML tags, with no friendly tooling behind it. If a team wants to adopt it, the sensible move is to write it into the PR template or contributing guide, with a copy-paste snippet, so nobody has to remember the syntax. One technical tip from the comments is also worth keeping: leave a blank line after </summary>, or the Markdown inside the fold may not render.

Bringing it to your own repo: a template you can copy

If you want to try this in your own project, the cost of adoption is close to zero. Nothing needs to be configured; you only need to agree on a format. Here is one you can drop straight into a PR template or a team doc.

At the top, write one to three sentences in plain human language: what this change does, why it is being made, and anything reviewers should pay special attention to. Add a screenshot if one helps — for UI changes especially, one image is worth three paragraphs. Then a blank line, and the collapsed block: open with <details>, put the model name and effort level in <summary> — "Claude Opus 5.5 Medium" or "Codex High", for example — leave a blank line, paste the agent's full description verbatim, and close with </details>.

You can go one step further and add a rule to the agent's prompt: when it writes a PR description, ask it to produce the one-sentence opener and the full version separately. That makes the human's job of picking the opener even cheaper — mostly choosing one of the candidates and tweaking it. Willison's workflow already leans this way: he sometimes takes a sentence straight from the agent's own long text as the opener. Writing that split into the prompt semi-automates the "picking" step too.

When rolling this out to a team, start with the maintainers' own PRs. That is what Willison did: he used the pattern first in his own Datasette and llm projects, posted real examples, and then wrote the blog post explaining why. Maintainers going first teaches far more than ten rules in a contributing guide. Once people are used to it, put it in the PR template, so a first-time contributor learns the format on their very first PR.

One contrast is worth noting. In the same year Willison wrote this post, another engineer, Kenton Varda, chose the opposite approach — banning AI-generated descriptions from his team's PRs, commit messages, and tickets outright. His reasoning: AI descriptions repeat detail that is already visible in the code, while leaving out the higher-level framing. Willison does not dispute that judgement; he simply offers a gentler answer. The AI essay can stay, but it must first pass through a human judgement. A ban suits teams with extremely strict requirements for description quality; folding suits most teams trying to balance efficiency with readability. Neither is right or wrong — it depends on your team.

A mnemonic, and a judgement worth thinking about

Willison closes with a memory trick. He used to struggle to remember the order of the two tags — is it <details><summary> or <summary><details>? Two tricks helped him. First, and most obviously, the <summary> is the bit where you summarize the details — so it is the clickable line of text, and the <details> element wraps everything else. Second, always refer to the two tags as "details-summary": two syllables followed by three syllables, which rolls off the tongue more smoothly than the three-two punch of "summary-details". Say "details-summary" out loud a few times, and you will never forget the order again.

The mnemonic is small, but it reveals the attitude of the post: Willison is not publishing a grand methodology, just sharing a small habit that makes his daily work smoother. That "small habit" style is a large part of why his blog has stayed popular for years — no manufactured anxiety, no piled-up jargon, just things he actually uses, with real examples attached, leaving readers to decide for themselves whether to copy them.

The part of this post most worth thinking about, though, is not the technique itself but the judgement behind it: the flood of AI writing is forcing humans to care about editing again. The cost of writing has collapsed, but the cost of reading has not — so the editorial acts of filtering, distilling, and judging have become more valuable, not less. Willison's collapsed block puts editorial judgement in the most visible place: the conclusion first, the full text after. PR descriptions are one case; AI-generated documents, reports, and summaries are all the same. What we need to learn next may not be how to write more, but how to put one human sentence up front that is worth reading on for.

Closing: the etiquette of PRs in the AI era is taking shape

Zoom out, and the timing of this small habit is interesting. In 2026, coding agents like Claude Code and Codex have become everyday tools for many developers, and AI-drafted PR descriptions are turning from a novelty into the norm. The problem that follows is very real: reviewers face more and more AI-written essays every day, while their patience has not grown to match. Some choose to ban it, some choose to let it be, and Willison chose a third path — accept the value of the AI essay, but give it a human doorway.

The significance of that path goes beyond PR descriptions. It answers a larger question: when AI can write all the "correct and comprehensive" words for us, what human value is left in collaboration? Willison's answer is judgement — judging what is worth reading, what deserves attention, and what can wait. A one-sentence opener is the lightest form of that judgement. It does not require you to write better than the AI, only to think more clearly than it does.

So this post is worth reading not because it teaches an HTML trick, but because it models a way of working in the AI era: neither resisting AI nor handing everything to it. In a world where AI writes more and more, the person willing to spend thirty seconds thinking of one human sentence — and putting it right at the top — has become the scarcest collaborator of all. Next time your agent finishes a PR and writes its long description, don't rush to merge. Ask yourself one question first: if I could keep only one sentence, which one would it be? Once you know, put it at the top, and leave the rest to the collapsed block.

Views 10Comments 0

Comments (0)

ME
0/1000
Loading comments...

Sources

Browse projectsPublish your project

Related articles

A developer with glasses types on a laptop at a wooden desk, an external monitor to the left showing C code on a dark background, a small plant on the desk
News
Microsoft's Coding Model Stops Playing Second Fiddle: MAI Code 2 Scores 96% of Opus 5.5 for 5% of the Cost — Read the Three Caveats First

On 17 November 2026, Microsoft launched MAI Code 2 and Code 2 Flash: the larger model has 77 billion active parameters and a one-million-token context, averaging 63.2% across four benchmarks — close to GPT-6.1 Sol and Claude Opus 5.5 — at $0.309 per task. Read the three caveats first: promotional pricing, the lowest score of the three, and no long-horizon work.

Developer WorkflowProduct LaunchModel Updates
A developer types at a dual-monitor workstation; the left screen shows a dark code editor, the right a testing dashboard with green checkmarks and bar charts
News
Did Your Agent Get Better or Worse? AWS Open-Sources UAEF to Measure Agents from Every Framework with One Ruler

On 11 November 2026, AWS open-sourced UAEF: adapters turn traces from LangGraph, LangChain, Strands and Bedrock AgentCore into one format, then 36 metrics across 7 dimensions score them, flagging regressions past 5%. The judge model is hardened too — scores must cite verbatim evidence, and never decide safety.

Developer WorkflowProduct LaunchTesting & Quality
Against a black background, a conductor seen from behind raises a baton, with swirling trails of light circling beneath him like an orchestra being conducted
News
One API for 45 Models, and It Switches Providers When One Fails: Perplexity's Orchestrator Wants to Be the Switchboard

On 17 November 2026, Perplexity launched the Orchestrator API: one interface reaching OpenAI, Anthropic, Google, xAI and open-weight models such as GLM, Kimi and DeepSeek, billed at the answering model's published rate with no platform fee. When one provider fails, the same model retries on another deployment, and preview routing assigns requests to models by task.

Developer WorkflowProduct LaunchModel Updates