No AI tool will make your PR descriptions worth reading until you write the why yourself. The model can’t know why the change exists, and that’s what a reviewer needs most.
Engineer Colin Breck makes this case in I Don’t Want to Read What You Didn’t Write. It reached #3 on Hacker News on September 22 and passed 1,000 points and 450 comments (thread).
Table of Contents
- Why AI-written PR descriptions lose reviewers
- Why a better prompt won’t fix it
- Write the why yourself, then let AI check it
- How to write a PR description reviewers read
- FAQ
- Sources
Why AI-written PR descriptions lose reviewers
Breck keeps running into the same workflow. Someone builds a feature with AI, then has the AI write the design document afterward. A design doc used to be how you built agreement before writing code. Written after the fact by a model, it becomes a long, flat summary that nobody engages with.
Pull requests get the same treatment. The generated summaries he describes list every rename, split, merge and new test. They leave out whether the change matters, how risky or urgent it is, and where the author wants help.
He also cites a survey by Cynthia Dunlop on blog posts readers suspect are AI-written. 78% stop reading and 71% avoid that author afterward. 98% prefer the author’s own imperfect draft to a polished AI rewrite. That survey covered blog posts, not pull requests. I’d expect reviewers to feel the same, with one difference: a reviewer can’t stop reading your PR. My guess is they finish it and trust you a bit less next time.
Readers now suspect AI fast. People now associate the “isn’t just X, it’s Y” construction with LLMs. A few commenters spotted it in one of Breck’s own sentences. Others replied that it could be deliberate, or simply a phrase people have always used.
Why a better prompt won’t fix it
I found this the most useful part of the essay. When you prompt a model, you already know everything behind it: the constraints, the logs, the code, the dead ends. You read the output with all of that in your head, so it seems clear and is easy to skim.
Your reviewer has none of that context. They read every line and guess which parts matter. A document that works for the person who prompted it can be close to unreadable for anyone else.
One commenter framed it as information transfer. If you have 1,000 bits to get across and hand the model 300, it can’t know the other 700. Whatever it adds is padding the reader has to filter out. You might as well send the 300 yourself.
Prompting for a better style helps with tone only. One developer tells Claude to write like a human, in full sentences with no filler. Their plan docs became much easier to understand, though they still revise each one before sharing it. The reasoning still has to come from you.
Write the why yourself, then let AI check it
Breck isn’t against AI, which is easy to miss if you only read the title. He recently wrote an academic paper with heavy AI help, and the model didn’t write a sentence of the body. After each paragraph, he asked it to check his text against the source code, configuration, production logs and metrics. That covered details like which database columns were indexed or how Parquet rows were sorted. It also caught a notation error that four expert human reviewers had missed.
He used it for citations, spelling, grammar, shorter sentences and TikZ diagrams too. He also tried the reverse, having the model write a paragraph from the code. The result was unpleasant to read and often wrong. The one part it wrote well was the abstract, which he kept as is. I’d copy that split: you write the argument and the model checks it.
The strongest pushback lands here. Not everyone thinks in clean prose, one commenter argued. AI helps some people turn a real idea into something they can share. The more the essay’s complaint gets repeated, the more elitist it sounds to them. I think that’s fair. If writing is hard for you, a model can help, as long as the ideas are still yours.
Another developer drew the line I agree with most. Using AI to tidy a messy bullet list is fine. What people hate is a model turning that list into prose that pretends someone thought it through. Their advice to people who rely on AI: send the cleaned-up bullets and skip the essay.
How to write a PR description reviewers read
Everything below is about making the reviewer’s job smaller.
- Lead with why. Write one or two sentences in your own words about the problem this solves. The diff already shows what changed.
- State the risk plainly. Can it be rolled back safely? Does it touch data or auth? Is it urgent?
- Point at the part you’re least sure about, down to the file or function.
- Size the description to the change. A 20-line fix doesn’t need a risk essay.
- Use AI to check your description against the diff and catch typos. Don’t ask it to explain your own change and paste the answer.
- Never reply to review comments with an AI summary of those comments. Breck says someone did this to him. I can’t think of a faster way to lose a reviewer’s goodwill.
Step 4 has a reviewer’s complaint behind it. One commenter now pushes back on PRs where a 20-line change comes with pages of generated risk analysis. Approving the PR implies they read and accepted all of it.
A description can be this short:
Why: checkout retries were double-charging when the payment
provider timed out after accepting the charge.
Risk: medium. Touches the retry path only; easy to revert.
Look at: idempotency key handling in retry.go, I'm not sure
the TTL is long enough.
It’s quick to read, and a model couldn’t have written any of it from the diff.
One counterpoint limits all of this. Some teams have stopped reviewing PRs at all, another commenter added. One model writes the code, another reviews it, and CI merges. On those teams it’s fair to ask who the description is even for.
The reviewer’s side, including a checklist for AI-generated diffs, is in Reviewing AI-generated pull requests.
FAQ
Is it wrong to use AI to write pull request descriptions?
Using AI to check your description against the diff, fix grammar or tidy a list is fine. Letting it write the reasoning is where it goes wrong. The model doesn’t know why you made the change, and that’s what the reviewer needs most.
What should a good PR description include?
Why the change exists, how risky it is, and where you want the reviewer to look. Keep the length in proportion to the change; a small fix needs a few sentences.
Why does an AI-written description read fine to me but not to my reviewer?
You prompted the model, so you read its output with the constraints, logs and dead ends already in your head. Your reviewer has none of that context. They read every line and guess which parts matter.
Did the Hacker News thread agree with Colin Breck?
Mostly, with real pushback. Some commenters said AI helps people who struggle with writing share their ideas. Others said AI-tidied bullet points are fine and only fake prose is the problem. A few pointed out that the essay itself uses a phrasing associated with LLM writing.
Sources
- Article: I Don’t Want to Read What You Didn’t Write, by Colin Breck.
- Discussion: Hacker News thread, for the information-transfer framing, the pushback on who AI-written prose actually helps, and the note on PR review norms when agents write and review the code.