AI PM Ready
Back to the Digest

AI-Generated PR Descriptions Can Be Too Good: Use HTML Details/Summary for Human-Readable Summaries

Simon WillisonPM Craft3 min readImportantOriginal source ↗

AI coding agents are writing PR descriptions that are too comprehensive, leading to developer fatigue and a tendency to skim or ignore them. Using HTML’s `<details>` and `<summary>` tags provides a collapsed view, allowing developers to see a human-approved introduction before diving into the AI-generated details. This tackles the challenge of information overload from AI-assisted development, making code reviews more efficient. This week, explore implementing `<details><summary>` for AI-generated documentation in your PRs. Watch for AI agents that can learn to summarize their own output effectively for human consumption.

What happened

Simon Willison notes that AI coding agents, like Claude Code and Codex, are producing PR descriptions that are highly accurate and comprehensive. However, this comprehensiveness makes them feel like 'slop' to human readers, who are instantly put off by the perceived reading time. The solution proposed is to use HTML’s `<details>` and `<summary>` tags, which allow the detailed description to be collapsed by default, presenting only a brief, human-approved summary. This is supported in GitHub Markdown, offering a practical way to manage the output of AI code generation tools.

A scenario you might face

A product team is using an AI agent to assist with code development, and the agent is generating detailed PR descriptions. Developers are finding these descriptions overwhelming and are skipping over them, potentially missing critical information or context. The PM needs to implement a solution that makes these descriptions more palatable without losing the valuable information. Using the `<details><summary>` HTML structure, the team can present a concise summary generated by the AI (or a human-edited version) with the option to expand for the full, detailed AI-generated description, balancing completeness with readability.

What changes in your practice

In your next PR, when using an AI code generation tool, add a `<summary>` tag containing a brief, human-friendly overview of the changes. Then, enclose the AI-generated, more detailed description within the `<details>` tags. This will make your PRs more digestible for your team this week. Before your next sprint review, discuss with your engineering team how AI-generated documentation is impacting their workflow and identify other areas where summarization or progressive disclosure could be beneficial.

Questions for your team

  1. 01What are the specific criteria for a 'human-approved introduction' to an AI-generated PR description?
  2. 02How can we measure the impact of using `<details><summary>` on code review efficiency and developer comprehension?
  3. 03Should we train the AI agent to generate both a concise summary and a detailed explanation, or rely on human editing for the summary?
  4. 04What are the long-term implications for developer onboarding and knowledge transfer if AI-generated documentation becomes the norm?

Practise this

Interviewers ask about stories like this one. Rehearse your answer in a timed mock interview.

Start a mock interview →
All stories
Was this page useful?