Give Every Pull Request a Changelog
September 28, 2026
Once you have agents working on several problems at the same time, the review queue can fill up quickly. You open a pull request, work out what it changes, review it, and move on to the next one. By then, there may already be more waiting.
Some of that work requires careful engineering judgment. Some of it is the repeated effort of figuring out what you are looking at.
What will be different when this merges? Which part of the system is affected? Does it depend on another change?
I want those answers before I start reading the implementation.
That is the idea behind pr-changelog: a small agent skill that puts a short, structured changelog at the top of a pull request description.
When we update an open-source dependency, its changelog gives us a starting point. We can see which capabilities were added, which behaviours changed, and whether something needs our attention. We can then investigate the details that matter to our use of the library.
I think that convention is useful inside an application, too. A pull request is a proposed change to something other people depend on. It should make the consequences easy to understand.
A description can contain plenty of information and still leave that work to the reviewer. Imagine a PR that introduces an invoice filter. Its summary might say:
Added a status parameter to the invoice endpoint, updated the query builder, and connected the new dropdown to the frontend state.
That tells me how the feature was implemented. The changelog can start with:
Added — Invoices: Filter invoices by payment status.
Now I know what the change is for. The implementation details still belong in the description below it, where they can support the review.
The distinction becomes more useful as PR descriptions grow. An agent can produce a detailed account of every file it touched. The reviewer still needs someone to decide which consequences deserve attention.
The skill makes that an explicit part of the task. It asks for short, categorised bullets, with roughly thirty words per bullet and one consequence at a time. Added, Changed, Fixed, Removed, and similar categories provide a familiar structure. A dependency on another PR gets an explicit heads-up.
The level of detail follows the change.
A UI change should explain what a user can now see or do. An integration change should describe the system's observable behaviour. A change to shared infrastructure may need to name a module, table, or resource to be useful.
Technical language is appropriate when the change is technical. Trying to turn every database migration or queue change into a customer benefit can obscure the information an engineer actually needs.
The skill also asks the agent to be selective. If a PR delivers a visible feature, the internal plumbing behind it does not need a separate changelog bullet. A PR that consists entirely of internal work can have a brief Internal entry. Test counts and implementation explanations can stay in the rest of the description.
The changelog gives the reader a useful first view of the change. It needs to be short enough that people will actually read it.
But brevity only helps if the entry is grounded in what changed.
The workflow starts by gathering the PR's metadata, commit messages, changed files, existing description, and a linked task when one can be found. The agent is then instructed to read the actual diff. Commit subjects alone are insufficient. The task can explain why the work exists; the diff shows what was implemented.
That matters because a task description expresses an intention. The implementation may cover only part of it, or take a different approach. A changelog based entirely on the original request can describe a result the code does not deliver.
The skill therefore requires the agent to describe only changes it has seen in the diff and to acknowledge ambiguity when necessary.
There is also a small Python helper behind the workflow. Its role is deliberately mechanical: gather context and insert the finished changelog into the PR description. The agent writes the prose.
The helper puts the changelog inside marked boundaries at the top of the description. On subsequent runs, it replaces the previous block while preserving the surrounding content. It saves the old description before writing, supports a dry run, and refuses malformed or duplicated markers.
This keeps the editorial judgment in the skill and gives the repeated editing operation a predictable implementation. The same workflow can refresh the changelog when a PR changes materially during review.
A good changelog still leaves the reviewer with work to do. It does not establish that the code is correct, the tests are sufficient, or the design is appropriate. The agent writing it may carry the same mistaken assumptions that shaped the implementation.
Its value is in helping the reviewer orient themselves and direct their attention. A clear statement of the intended behaviour also gives them something concrete to check against the code.
This connects to a broader idea I have been thinking about: treating well-defined parts of an application more like dependencies. Clear boundaries, explicit contracts, and understandable changes can help us reason about a growing system without reconstructing every detail on every occasion.
That approach requires trustworthy boundaries and verification. Adding a changelog is one small, practical step toward making changes easier to assess.
As agents take on more implementation work, explaining that work should be part of their job. The first thing I want to read on a pull request is what will be different when it lands.