Coding with AI

Use collapsible HTML details and summary tags to hide your low-quality Pull Request descriptions.

Collapsible details-summary blocks let humans add a short Pull Request opener first and hide long agent notes, helping reviewers judge relevance.

Key Takeaways

  • Long AI-agent pull request descriptions can overwhelm reviewers, even when accurate, so they should not be the visible opening text.
  • Add a short human-curated summary at the top to explain the purpose and help reviewers decide whether to read further.
  • Hide the full agent-written description inside collapsible GitHub `details` / `summary` blocks to keep detail available but optional.
  • Use a collapsed label that names the agent model and effort level, such as `Claude Opus 5.5 Medium`, to clarify the source of the long text.
  • Include screenshots when useful, and remember that `summary` is the visible clickable heading while `details` wraps the hidden content.

Meta description: A practical pattern for GitHub pull requests from Claude Code or Codex: put a short human summary first and hide agent details in details-summary.

Tags: GitHub, Pull Requests, Claude Code, Codex, Markdown

Featured image: ![Abstract friendly illustration of a code review page with a collapsed details section, rounded cards, arrows, soft colors, no text](code-review-details-summary.svg)

Many project changes now arrive as pull requests opened by Claude Code or Codex. A pull request is the unit of work: it groups commits, holds iteration until a feature is finished, records decisions, and becomes the merge target. The challenge is that modern coding agents produce descriptions that are so complete they can discourage review. They explain the problem, the detailed solution, and verification steps. That accuracy can make the opening text feel like a wall. The fix is not to delete the agent's work. It is to add a human decision at the top: a short note that tells a reviewer what the pull request is for and whether it deserves attention.

Why agent-written descriptions can feel heavy

An agent-written pull request description can be accurate, comprehensive, and still hard to absorb. It is not necessarily slop, but it can read like slop. It is easy to spot agent-written text, and the immediate reaction can be that a reviewer will not read all of it. The length can put a reviewer off even when the information is useful, and even when the author of the pull request is also the reviewer.

A human editorial judgement is what is missing. The reviewer wants someone to think just long enough to produce a human-approved introduction, not a full essay. That introduction should help the reader understand the purpose at a high level and decide whether to keep reading.

The GitHub details-summary pattern

The HTML details and summary elements solve this by creating a collapsed block. The summary becomes the visible heading, and the details content is hidden until the reader clicks to expand it. GitHub Markdown supports these tags, so they can be placed directly in a pull request description or issue comment. GitHub displays the summary plus an expansion arrow and hides the larger text.

In practice, the opening paragraph is the human-curated part. It should be the shortest text a reader can use to get up to speed. A screenshot can also be added, because images often show a new feature faster than prose. The full agent-written description then follows inside a details-summary block. The summary label can be the model name and effort level, such as Claude Opus 5.5 Medium. That makes the source of the long text clear.

The information is still present, but a reviewer can glance at the top and skip the expanded section if it is not needed. The author does not always write the introduction manually. Sometimes the agent has already produced a useful short opener buried in the longer text. The visible opener is still a promise to the reader: this is the human judgement about what is definitely worth their time.

Steps for using it on agent pull requests

  1. Let Claude Code or Codex open the pull request and generate the full description.
  2. Read the agent text only far enough to understand what the pull request is trying to accomplish.
  3. Write or select a short opener that gives the high-level purpose and the main change.
  4. Add a screenshot if it helps a reviewer understand the feature quickly.
  5. Move the full agent description into a details-summary block.
  6. Use a summary label that names the agent model and effort level, such as Claude Opus 5.5 Medium.
  7. Check that GitHub renders the summary as a collapsed heading with an expansion arrow.
  8. Keep the opener as the human-approved part, even if it was chosen from agent text.

Examples and the mnemonic

The pattern has been used in several recent pull requests.

  • In datasette pull request #3052, titled Redesign row page as a vertical list of fields, the opener explained that the row page had shown a single row as a one-row table. For wide tables, such as a 46-column GitHub repos table, that layout scrolled far to the right and left much of the page blank. A screenshot followed.
  • In datasette pull request #3043, titled Pagination bar showing which rows are on the current page, the opener said that table pages spanning more than one page now make the current location clear and provide navigation at the top as well as the bottom. A screenshot was also included.
  • In datasette pull request #3042, titled Load edit-tools.js on demand via a small loader, the opener explained that edit-tools.js, approximately 220 kilobytes, was loaded on every table, row and database page, even for users who could not edit anything. The new behavior loads it only for users who can edit when they first interact with an edit feature, including mouse over an edit link.
  • In datasette-agent pull request #51, titled register_agent_reference_types plugin hook, the opener described a hook that lets plugins add their own kinds of item to the # tagging in the chat composer through register_agent_reference_types(datasette).
  • In llm pull request #1838, titled Add llm openai endpoint add/list/remove/path commands, the opener said the commands manage records in extra-openai-models.yaml so OpenAI-compatible endpoints can be saved from the command line instead of hand-editing YAML. The pull request also included copied --help output.

The author had trouble remembering whether details or summary comes first. The simple rule is that summary summarizes the details, so summary is the clickable line and details wraps everything else. Calling the pair details-summary also helps: it is two syllables followed by three syllables, and it flows better than summary-details. Saying it out loud can make the order stick. The author still wishes GitHub would add a Markdown editor button for this, partly to save typing on a mobile keyboard and partly to spread awareness of the feature.

Common mistakes

  • Opening with the full agent essay. If the reviewer sees many paragraphs first, they may not expand or read further.
  • Hiding the human opener. The summary should be visible; the collapsed block should contain the detailed agent explanation.
  • Using an unclear label. A summary line such as Claude Opus 5.5 Medium tells the reader what is inside and why it may be long.
  • Over-editing the opener. It only needs enough high-level context to decide whether to look deeper.
  • Assuming the pattern works outside GitHub Markdown. It is described as supported in GitHub Markdown for pull requests and issue comments.

Comments (0)

  1. No comments yet. Be the first to share what worked for you.

Leave a comment

Comments are reviewed before they appear. Your email address is not published.