PR Bottlenecks: What We Are Doing About Them

We hit a wall earlier this year. Small team, 15+ PRs a day, most of them agent-generated. Code was landing faster than people could review. PRs piled up. Reviews got thinner. The thing that used to be the cleanest part of our workflow — open PR, get two reviews, merge — turned into the weakest link.

The interesting part isn't that this happened. It's that we couldn't fix it the way we used to. The old levers — bigger PRs "to save review time," required reviewer counts, SLA timers, bot reminders — were designed for a world where humans were the bottleneck on writing code, and humans were also doing the reviewing of code. When the writer side gets an order of magnitude faster, every one of those levers misfires.

So we ran an experiment. And it's working well enough that we packaged it and open-sourced it: ver-pr-writer, an agent skill that generates reviewer-focused pull request descriptions using explicit PR signals. You can install it right now:

npx skills add Vermonster/ver-pr-writer

This post is half announcement, half postmortem. The why is the part we wish someone had written down a year ago, so we wrote it down now.

What the bottleneck actually is

The first thing to internalize is that the bottleneck moved. It used to be code production. Now it's review.

For a long time, "PR review" was shorthand for "a human looks at every line of a diff and decides if it should land." That model is collapsing under agentic coding. When a single small team can produce 15+ PRs a day, and each PR is being generated in part by a model that also produces a perfectly formatted diff but no clue about why the change is correct, the problem isn't reviewer speed. It's that the reviewer's job changed and the process didn't.

Three things start going wrong, all at once:

• PRs are too big to read and too small to design. A 200-line change touching one file is easy to review and easy to think about. A 200-line change touching 14 files is hard to review and impossible to think about. Agent-generated PRs drift toward the second shape because the agent doesn't feel the cost of an extra file the way a human does.
• PRs don't carry enough context. A diff tells you what changed. It doesn't tell you why, where the risk is, what was validated, what the agent already checked, or what still needs a human opinion. Every reviewer — human or agent — has to reconstruct that from scratch, every time, from the raw diff. That doesn't scale.
• Reviews get thinner as the queue grows. When there are 20 PRs open and the team is shipping 15 a day, the most rational thing for any individual reviewer to do is approve the ones that "look fine." The rubber-stamp feedback loop is the natural endpoint of the old model at this volume.

The first lever people pull is "review faster." That's a trap. The constraint is reviewer attention, not reviewer time, and attention is not something you can buy more of. The real fix is to make each PR cheaper to review correctly. Stop optimizing for the click-through.

What we tried that didn't work

A short, honest list, in case you're considering them:

• Bigger PRs "to save review time." This is the most seductive wrong idea. The reasoning goes: if reviewers are slow, give them fewer, fatter PRs. In practice, the PRs got fatter and the reviews got shallower. We were losing signal, not gaining time. The fatter PRs also dragged in more agents, more auto-generated files, more renames, and more "while I was in there" changes. The opposite of what we wanted.
• Required reviewer counts. Set to two, reviews got slower because every PR needed two calendars to align. Set to one, reviews got shallower. Set to one-of-a-domain-expert, the queue moved to the experts' queue. None of these were durable fixes; they were all reshuffling the same attention budget.
• SLA timers. "Review within 24 hours." The SLA gets met, but the review inside the SLA is the one that paid the SLA tax. We started measuring what we wanted to fix and stopped measuring what actually mattered — the quality of the review, not its existence.
• Bot reminders. "@reviewer please review this PR." The bots did their job. The reviews didn't get better. People just got better at ignoring the bot.

What all of these have in common is that they treat review as a queue-management problem. It isn't. It's a signal-density problem. The fix is upstream of the queue.

What changed when we added agents to the pipeline

A thing started happening in the months leading up to the wall: a lot of what used to eat human review time stopped needing a human.

Agent reviewers and pre-merge checks were catching:

• Policy adherence (lint, format, style, naming)
• Code architecture and module boundaries
• Test coverage gaps
• Documentation drift
• Code quality heuristics (dead code, redundant logic, suspicious patterns)
• Mechanical refactor opportunities

That's most of what a typical PR comment thread is. Not all of it — far from it — but most of it. And if the machine concerns are handled upstream, the human review job changes shape. A human reviewer in an agentic pipeline shouldn't be re-checking that the formatting is consistent or that the test file has a corresponding .test. They should be doing the thing only humans are good at:

• Does this change make sense in the domain?
• Is the mental model coherent?
• Is the design decision right for this system, at this moment?
• What's the user-visible or system-visible behavior, and is it what we want?
• Where is the risk concentrated, and is it understood?

That's judgment work, not inspection work. The review process we had was built for inspection. So even with the upstream improvements, the PR descriptions themselves were still raw diffs and commit messages, and the reviewers were still trying to reconstruct intent from scratch. The upstream fixes helped; they weren't enough.

The hypothesis: PRs as signals, not diffs

So we tried an experiment. Instead of making reviews faster, we made PRs more focused for humans to review.

The hypothesis was simple. A good PR description should let a reviewer answer five questions in under a minute:

1. What is this trying to do?
2. What could go wrong, and how serious is it?
3. What tests or validation support the change?
4. Where should review attention go — and where should it skip?
5. How does this behave when merged and deployed?

If a PR carries all five, a reviewer — human or agent — can do much more than summarize. They can:

• Classify the PR and route it appropriately
• Challenge weak claims
• Identify missing evidence
• Focus attention on the parts that actually need it

If a PR carries none of them, no amount of reviewer time fixes it. The diff is the same, the comments will be the same, and the rubber stamp is the same.

We called this structure PR signals, and we built a vocabulary around it. Nine categories, distilled from the patterns that kept showing up in real PRs — both good and bad:

Two of those — change shape and the mechanical parts of others — can be derived automatically. The rest are author-provided. The author-provided ones are the ones that change review quality the most.

We didn't adopt the whole thing on day one. We adopted the minimum viable set — the categories that consistently produced a real difference in review quality:

Purpose · Mental model · Main changes · Risk level · Risk areas · Review hotspots · How to test locally · Expected behavior · Non-goals · Rollout/migration notes if applicable

That was enough to transform the process. We started requiring those sections on every PR. We started teaching agents to generate them. And we started tracking review quality signals, not just review throughput.

The results, after a few months:

• Rubber-stamp reviews dropped. When the PR explicitly states its risk level and its review hotspots, the reviewer can either engage with the stated risk or push back on the stated classification. The "looks fine, ship it" pattern becomes hard to sustain.
• Real bugs got caught earlier. Validation signals make missing validation visible. Risk signals make the dangerous parts obvious. Reviewers stop skimming the whole diff and start looking at the parts the author flagged as risky.
• Reviews got faster, not slower. Yes, the PR descriptions are longer. The reviews got faster because reviewers no longer have to reconstruct intent. Time-to-first-meaningful-review dropped more than time-to-write-description rose.
• Agents got dramatically more useful. When an agent reviewer has the same structured signals a human does, it can challenge weak claims, identify missing evidence, and route attention. The human/agent review loop becomes coherent instead of two parallel guesses.

It was the smallest intervention that produced the largest change.

Introducing ver-pr-writer

Here's the part where we admit we did eventually build a thing.

ver-pr-writer is an agent skill that does the PR signal work for you. You point it at a branch, and it inspects the diff, commit messages, changed files, and test coverage, classifies the change, surfaces risk and uncertainty, and produces a structured PR description that both humans and agents can act on immediately.

npx skills add Vermonster/ver-pr-writer

You can also install it for a specific agent:

npx skills add Vermonster/ver-pr-writer -a github-copilot
npx skills add Vermonster/ver-pr-writer -a claude-code
npx skills add Vermonster/ver-pr-writer -a cursor

It runs in two modes:

• Draft mode (default). Generates the PR description and displays it. Nothing is created or modified on GitHub. Use this to review and iterate. Draft is the default for a reason — most of the value of signal-structured PRs is the thinking, not the pushing.
• Submit mode. Generates the description and then creates or updates the pull request on GitHub (using the GitHub Pull Request tool when available, falling back to gh CLI). Always confirms before doing anything destructive. New PRs are created as drafts by default.

The skill ships with everything you need to make the workflow stick in your team:

The skill also has a built-in mismatch detector. After it drafts the description, it goes back and checks the generated signals against the actual diff — catching things like "stated as low risk, but the diff touches auth, config, and persistence," or "refactor that adds behavior and a migration." Those are the exact mismatches that turn into production incidents, and they're the ones human reviewers miss when they're tired at the 14th PR of the day.

Adopting it in your team

You don't have to use the whole skill to get value. The shortest path that works:

1. Copy the PR template. Drop reference/pr-template.md into your repo as .github/pull_request_template.md. Now every PR has the signal structure as the default scaffolding.
2. Copy the CI workflow. Drop reference/pr-signal-check.yml into .github/workflows/. Now required sections are enforced, not optional. The check is intentionally soft — it tells you what's missing, it doesn't block the PR — but the visibility is enough.
3. Install the skill in your agents. Now your agents generate signal-compliant PR descriptions by default.

If you only do step 1, you'll get the structural effect (PRs carry context). If you do steps 1 and 2, you'll get the team-wide effect (every PR has the same shape, so reviewers know what to look for). If you do all three, you get the compound effect: humans and agents operate against the same signal contract.

We recommend doing all three. We've also found that the order matters — install the skill after the template is in place, so the agent has something concrete to follow rather than improvising.

What this is not

A few things this isn't, so nobody's surprised:

• It's not a replacement for review. The skill produces a better PR description; it doesn't review the code. That's still on humans and agents downstream. The signal structure makes that review targeted, not replaced.
• It's not a linter. It doesn't check code style or test coverage. Those belong in your existing CI. This skill lives in a different layer — the human-intent layer above the code itself.
• It's not magic. A signal-structured PR is only as good as the signals in it. If the author (human or agent) declares "low risk" on a change that touches authentication, the skill's mismatch check will catch it — but only if you let the skill compare the signals against the diff. We strongly recommend always running it in draft mode first so a human can sanity-check the generated signals.
• It's not a "we figured it out" post. It's a "we hit the same wall you're hitting, here's what we tried, here's the part that worked, here it is, tell us what you'd change" post. The skill is v1.1.0. We have a roadmap and we have gaps.

What we want feedback on

We built this for ourselves first and shared it second. That order matters: the v1 reflects what we needed, not necessarily what you need. So:

• Try it on a real PR and tell us where the signals fall short. The nine categories came from patterns in our own work. Yours may diverge. We want to know which signals earn their place and which ones feel like ceremony.
• Tell us which agent integration is missing. The skill currently installs for Claude Code, GitHub Copilot, and Cursor. If your team lives in something else, open an issue. We're not picky.
• Tell us if the CI enforcement is too strict or too loose. The shipped workflow is intentionally soft. We have opinions on stricter versions; we'd like to know if anyone wants them.
• Tell us what the right required set is. The maintainers' recommended required set is the ten signals listed above. That might be too many for some teams and not enough for others. We want to hear where the right floor is.
• Open issues, send PRs, fork and customize. The repo is MIT. If your team needs a fork, please fork. The five-bucket backbone (Intent, Risk, Evidence, Focus, Operations) is the part we'd ask people to keep; the rest is fair game.

You can find the project at github.com/Vermonster/ver-pr-writer. The full reasoning behind the signal categories lives in MOTIVATION.md in the repo — it's the long version of what we just walked through here.

The part under the part

Here's the thing under the part: the AI coding wave didn't break PR review. It revealed that PR review was always the wrong shape. The old model — humans reading every line, catching every nit, slow and careful — was a luxury that a low-throughput development process could afford. As soon as code production sped up, the old model stopped working. The question was always going to arrive. It just arrived faster than we expected.

The fix isn't to slow code production back down. It's to redesign the review layer for the world we're actually in. Signal-structured PRs, agent-generated or human-authored, are a small part of that. Domain expert pairing, judgment-focused reviewer roles, agentic pre-merge checks, and a dozen other shifts are all part of it. None of them are optional, and none of them are a substitute for caring about what ships.

The PR bottleneck isn't a process problem. It's a signal problem. We've been treating it as a process problem. That's why the old fixes didn't work. Better signals do.

ver-pr-writer is one experiment in fixing it. Try it. Break it. Tell us where it lands short. The next version should be shaped by the teams using it, not just by the team that wrote it.

Thanks for reading. And if you're a small team drowning in PRs right now: you're not alone, and you're not doing it wrong. The system was doing it wrong. It's getting fixed.