Coding agents write excellent PR descriptions. They document the problem, the solution, the verification steps, and every edge case. The result is accurate, comprehensive, and completely unreadable.
Simon Willison just published a simple pattern that fixes this: hide the agent-written essay behind a <details><summary> block and write a one-paragraph human summary at the top. The agent’s work is still there, but the human approval gate now has a scannable interface.
The Human Review Problem
When Claude Code or Codex opens a PR, it generates a description that covers:
- Problem statement
- Detailed solution architecture
- Implementation steps
- Verification procedures
- Edge cases and trade-offs
This is useful documentation. It is also instant slop. The human reviewer (often the same person who prompted the agent) sees a wall of text and thinks “I’m not reading all of that.”
The information density is high, but the cognitive load is higher. Agent-written text takes longer to read than it took to generate, even when you are the one who asked for it.
The Pattern
Willison’s solution is a two-layer PR description:
- Human-curated opener: One paragraph (or a screenshot) that explains what the PR does and why it matters
- Collapsible agent output: The full agent-written description wrapped in
<details><summary>
GitHub Markdown natively supports <details><summary> without plugins or extensions. The syntax:
This PR loads edit-tools.js (~220KB) on demand instead of on every page load.
<details>
<summary>Claude Opus 5.5 Medium</summary>
## Problem
The edit-tools.js bundle was loaded on every table, row, and database page...
## Solution
Implemented a lazy loader that only fetches edit-tools.js when...
## Verification
Tested with Chrome DevTools network panel...
</details>The collapsed state shows only the human summary and the model name. The reader decides whether to expand.
Implementation Details
The pattern enforces a specific workflow:
- Agent writes the PR and generates a description
- Human reads the agent output
- Human writes (or extracts) a one-paragraph summary
- Human wraps the agent text in
<details><summary>Model Name</summary>
The human editorial step is mandatory. You cannot skip it without leaving a wall of text at the top of the PR.
Real Examples
From Willison’s projects:
| PR | Human Opener | Agent Detail Length |
|---|---|---|
| datasette #3052 | ”The row page showed its single row as a one-row table. For wide tables, like a 46-column GitHub repos table, that scrolled far off to the right.” | ~15 paragraphs |
| datasette #3043 | ”Table pages that span more than one page now make it obvious where you are, and offer navigation at the top of the page as well as the bottom.” | ~12 paragraphs |
| llm #1838 | ”Adds commands for managing the records in extra-openai-models.yaml, so OpenAI-compatible endpoints can be saved from the command line instead of by hand-editing YAML.” | ~10 paragraphs |
Each opener is under 50 words. Each collapsed block contains the full agent-written documentation.
Why This Works
The pattern solves three problems:
Cognitive load: The human reviewer sees a scannable summary first, not a wall of text.
Approval gate: The human must read and synthesize the agent output to write the opener. This forces engagement with the actual changes.
Documentation retention: The agent’s comprehensive description is preserved for future reference, debugging, or onboarding.
The <summary> text also signals provenance. Willison uses “Claude Opus 5.5 Medium” or similar labels to make it clear that the collapsed text is agent-generated.
The Mnemonic Trick
The tag order is <details><summary>, not <summary><details>. Willison’s mnemonic: “details-summary” is two syllables then three syllables. Say it out loud a few times and the rhythm sticks.
The alternative mnemonic: the summary is what you summarize the details with, so <summary> must be inside <details>.
Trade-Offs
| Aspect | Benefit | Cost |
|---|---|---|
| Human time | Forces 2-5 minutes of editorial work per PR | Adds a manual step to the agent workflow |
| Review speed | Reviewers scan the opener, expand only if needed | None (collapsing is opt-in) |
| Documentation | Preserves full agent output for later reference | Requires discipline to not skip the human summary |
| Tooling | Works in GitHub Markdown today, no plugins | No editor button (must type <details><summary> manually) |
The main risk is that the human writes a lazy summary that does not reflect the actual changes. The pattern does not prevent this, it just makes it more obvious when it happens.
Workflow Integration
This pattern fits into agent-driven development at the approval gate:
Agent writes code → Agent opens PR → Agent writes description
↓
Human reads agent description
↓
Human writes/extracts summary
↓
Human wraps agent text in <details>
↓
Human approves and mergesThe human step is unavoidable. You cannot collapse the text without reading it first.
For teams, this pattern also signals which PRs have been human-reviewed. If the description starts with a wall of text, the human skipped the editorial step.
Technical Verdict
Use this pattern when:
- You are the primary reviewer of agent-generated PRs
- You want to preserve agent documentation without overwhelming reviewers
- You need a forcing function to ensure human engagement with agent output
- You work in GitHub (or any platform that renders
<details><summary>)
Avoid this pattern when:
- Your team already has a PR template that enforces human summaries
- You are generating PRs for external contributors who will not understand the collapsed text
- Your agent workflow includes automated merges (no human review step)
- You need the full description visible for compliance or audit reasons
The pattern is a UI trick that enforces a workflow discipline. It does not change the agent’s capabilities or the quality of its output. It changes the human’s relationship to that output by making the approval gate scannable.