Agent-Written PR Descriptions Are Too Good to Read. Fold Them, Don't Cut Them.

Start with how Willison actually works, because his setup is becoming common among people who run agents daily. "Most of the changes I make to my projects these days come in the form of PRs opened for me by Claude Code or Codex," he writes in his post on the technique (Willison). He describes the PR as his "unit of work": the place where commits get bundled, where he iterates until a feature is done, where decisions get documented before the merge.

That last role is the important one. A PR description used to be optional garnish on top of the code. When an agent did the work, the description is often the only written record of why a choice was made. You weren't in the room when the agent picked one approach over another. The description is the room.

So the agent writes a lot. Willison's summary of a typical agent description is precise: "An agent-written PR description is accurate and comprehensive. It describes the problem, the detailed solution, and the steps taken to verify it. That’s a lot of information to absorb."

Notice what he isn't complaining about. He isn't saying the descriptions are wrong, padded with filler, or hallucinated. His complaint is volume relative to attention. If you review five or ten agent PRs a day, every one of them arrives with a small essay, and you'll hit the point where you stop reading them properly by mid-afternoon.

The gotcha here is that the failure is silent. Nothing breaks when you skim a well-written description. The text looks responsible, the tests are listed, the reasoning reads cleanly. You approve. The cost only appears later, when the one paragraph that mentioned a changed default or a skipped edge case turns out to matter. Comprehensive writing that nobody reads in full gives you the appearance of documentation without the benefit of review.

Your first instinct will probably be to tell the agent to write less. Resist it. The detail is valuable; it just isn't valuable at the moment you first open the PR.

A small example from Willison's own week shows why. He built a nudibranch-themed Fabergé egg in Three.js, a 3D graphics library, then asked Claude (Opus 5.5 Medium, in regular Claude Chat) to port it to plain JavaScript in the same conversation (Willison on Hacker News). The original was 77KB. The port came back at 98KB. And the two versions weren't the same: "They aren't identical - you can see what Claude said about that in the transcript (I don't fully understand why it differed)."

Read that carefully. Willison is about as experienced an agent user as exists, and the explanation for why the output differed lived in the long-form text the model wrote, which he still didn't fully follow. If that conversation had been a PR, the paragraph explaining the discrepancy is exactly the paragraph a "keep it short" instruction would have cut. You'd be left with a working port that silently behaved differently from the original, and no record of the model's own account of why.

The same logic applies to his research habits. Out walking the dog, he wondered how hard it would be to build a SQLite function that turns strings like "-$1,234.56" or "12.5%" into numbers, and handed an agent a prompt asking it to "Explore the difference between building this as a SQLite extension in C v.s. in Rust - I want to compare performance and code complexity and size of the resulting .so" (Willison). A request like that produces a comparison with numbers, caveats and method. The method is what tells you whether to trust the numbers.

So the problem has two halves that pull against each other. The reader needs a short version to decide quickly. The record needs the long version to stay auditable. Any fix that sacrifices either half is a bad fix, and "write shorter" sacrifices the record.

Willison's specific proposal is in the title of his post: hide the agent's description behind a <details><summary> block, the collapsible element that shows a single line and expands to the full text when clicked (Willison). The human-facing summary sits on top. The agent's complete writeup is one click away, still in the PR, still searchable, still there when someone asks why.

This pattern of one body of content served in more than one shape isn't new, and you can find it in projects that have nothing to do with Willison. The OpenClaw project's 2026.11.2 release page opens with a plain statement: "The release notes and changelog contain the same content, presented in two formats" (OpenClaw release). That same page then lists dozens of contributor handles. A release with that many hands on it generates far more change detail than any single reader wants in one sitting, so the project presents the same facts in a form for scanning and a form for reference.

crewAI, the multi-agent framework, shows the machine-side version of the same instinct. Its 1.15.38 release adds a feature to "Tag eval usage spans with target and a per-evaluation" label (crewAI release). Put in user terms: the detailed record of what an evaluation did is captured and labeled so it can be found later, rather than dumped in front of whoever happens to be looking.

The common thread across all three is a split between what you need to decide and what you need to verify. Decision information goes on top, short. Verification information stays complete, but out of the way until called for. Willison's fold applies that split to the one document where most agent users currently feel the pain most sharply.

Here is where the tip turns into an argument about how you should configure agents. Our working frame at ClawBlog is the Harness Hypothesis: the value in AI tools sits less in the model than in the harness that connects the model to your actual work. PR formatting is a clean test of that idea.

Willison's PRs come from two different agents, Claude Code and Codex (Willison). He doesn't describe one model as better behaved than the other on description length. His complaint applies to both, because thoroughness is what good coding agents are tuned toward. That makes it a poor idea to wait for a future model to fix the reading problem. Thoroughness is what you want from it.

Models also change underneath you constantly. crewAI's same release that added labeled evaluation records also switched to "Make gpt-6-luna crewAI's default model everywhere" (crewAI release). If your PR conventions depend on the quirks of whatever model is the default this month, they'll drift every time a default changes. If they live in your agent's standing instructions, they survive the swap.

In practice this means the instruction belongs wherever your tool keeps persistent guidance: the project instructions file, the system prompt, the repository rules your agent reads before it starts. You'll want it phrased as a structure, not a length limit. Something like: open with a short human summary of what changed and what to check, then place the full agent writeup inside a collapsed block.

The pattern suggests a broader point about where users actually gain leverage with agents. Most people tune their experience by switching models. The more durable gains tend to come from shaping the agent's output to fit how humans review it. The fold costs nothing to adopt, works with any model that can write Markdown, and moves the burden from your attention to your configuration, where it belongs.

Take the skeptic's case seriously, because it is a good one. A collapsed block makes it easy to skim, and it makes it equally easy to never look. If the agent's description contains the sentence that matters, and that sentence now sits behind a click, you've built a system that rewards not reading.

The concern isn't hypothetical in the broader industry. Latent Space's November 6 roundup notes that Thinking Machines "explains how it caught early checkpoints bypassing guardrails" (Latent Space). The point for you isn't that your coding agent is scheming. It's that the labs themselves find problems by reading detailed records of model behavior. Oversight depends on someone examining the long version. A layout that quietly discourages that is a step toward less oversight, not more.

On the Autonomy Spectrum, which runs from copilot to full autonomy, the fold nudges you one notch toward autonomy: you're trusting the agent's own summary to tell you whether to open the details. Most agent failures we've covered come from deploying at the wrong point on that spectrum, and a reviewer who never expands anything has effectively moved to "auto-merge with a glance" without deciding to.

The answer to the objection is not to abandon the fold. It is to decide, explicitly, what is never allowed inside it. Three categories should always sit above the fold, in the visible summary:

• Any change to defaults, settings, permissions or data handling.
• Any test that failed, was skipped, or was modified to pass.
• Any place the agent says it is unsure, or where output differs from what was asked, the way Willison's egg port differed from the original (Willison on Hacker News).

With those rules in place, the fold hides routine explanation and keeps exceptions visible. Without them, it hides whatever the agent happened to write, which is precisely the risk the skeptic describes.

If you want to adopt the pattern this week, the setup is short. You'll want to add a standing instruction to your agent along these lines: write a summary of three to five lines covering what changed and what the reviewer should check; list any changed defaults, failed or skipped tests, and uncertainties in that summary; then put the complete description, including problem, solution and verification steps, inside a collapsed <details> block with a plain label such as "Full agent writeup."

That keeps every element Willison values in agent descriptions, "the problem, the detailed solution, and the steps taken to verify it" (Willison), while letting you decide in seconds whether a PR needs a deep read.

Now the mistakes you're likely to hit, in the order you'll probably hit them.

First, the summary and the full text will drift apart. The agent writes the summary last, from memory of what it intended, and the details block describes what it actually did. When they disagree, the details are usually right. Spot-check by expanding the block on a handful of PRs during the first week and comparing.

Second, the rendering may not match your expectation. Collapsible blocks display differently, or not at all, depending on where the text ends up: some notification emails and chat integrations show the raw text. Open one PR in each place you actually read them before you rely on the fold.

Third, you'll be tempted to stop expanding entirely once the summaries look reliable. That is the moment to set a rule for yourself, such as always expanding the block on anything touching permissions, money or user data. The fold exists to route your attention, not to replace it.

A final note on scope. Willison frames this around his own projects. Team settings add a wrinkle he doesn't address in the excerpted post: other people will read your agent's PRs with less context than you have. If that describes your setup, write the summary for the colleague who has never seen the feature, not for yourself.