How to Humanize a Pull Request Description After ChatGPT

Reviewers merge on trust and clarity, not on word count. ChatGPT PR descriptions enumerate files, say "various improvements," and bury the one question maintainers ask first: why are we doing this now?

Without a test plan, reviewers re-derive your QA. Without risk notes, they assume you did not think about production. Humanizing filler does not add the failing test you fixed.

Related: humanize README, API documentation, best practices for humanizing.

What reviewers need in the first screen

Section	Weak AI PR	Strong PR
Why	"Updates code"	User bug, metric, or tech debt with link
What	File list	Behavior change in one paragraph
Test plan	"Tested locally"	Commands or steps you actually ran
Risk	Omitted	Rollback, flag, migration, perf
Scope	Drive-by refactors	In or out of scope stated

Lock why + test plan before any model

Write these by hand from your branch:

1. Ticket / issue link (JIRA, Linear, GitHub issue)
2. Why now — user impact or incident in one sentence
3. What changed — behavior, not filenames
4. Test plan — bullet list of commands, browsers, or environments
5. Risk — flag, migration, backward compatibility, or "none"

If you did not run a test, do not publish it.

PR template skeleton

Adjust to your team, but most repos want:

## Why
[One paragraph: problem + link]

## What
[High-level behavior change]

## Test plan
- [ ] `npm test path/to/file.test.ts`
- [ ] Manual: login → settings → toggle X

## Risk / rollout
[Feature flag, migration, or N/A]

Section	Humanize?	Why
Commands in test plan	No	Reviewers may replay them
Ticket URLs / IDs	No	Traceability
Why / risk prose	Light, one pass	AI loves vague "improves UX"
Screenshots	No—capture real UI	Evidence

Paste Why and Risk paragraphs into Human Writes once. Re-run every command in the test plan after editing.

Before and after

AI description:

This pull request implements various enhancements to improve the overall user experience and code quality. Several files were updated. Please review when convenient.

After why + test plan:

Fixes HW-482: quota emails sent twice when webhook retries (Stripe idempotency gap). Adds idempotency key on quota.followup handler and dedupes by event_id. Test plan: pnpm test quota-followup.test.ts; replayed sample webhook 3× in staging—one email in Resend log. Risk: deploy before weekend batch job; no migration.

Second version gives motivation, behavior, tests, and rollout timing.

PR description vs README vs commit messages

Artifact	Audience	Lock first
PR description	Reviewers this week	Why + test plan
README	New contributors	Install that works
Commit messages	Future git blame	Imperative subject line

README polish: humanize README. PR is the review contract for one change set.

Small PR vs large PR descriptions

PR size	Description focus
Bug fix	Repro steps, root cause, regression test
Feature	User story, flag default, docs link
Refactor	Behavior unchanged; perf or risk note
Hotfix	Incident link, rollback plan, on-call ping

ChatGPT defaults to feature-template language on a one-line fix. Match template to change type before you humanize.

Workflow

1. Open draft PR early if your team allows it.
2. Fill why / what / test plan from your notes—not "summarize my diff."
3. Paste real command output or staging screenshots.
4. Optional: one Human Writes pass on stiff summary sentences.
5. Re-run tests after any prose edit near command blocks.
6. Request review with one line in Slack pointing to Why and Risk.

What not to do

• Let the model invent test results.
• List twenty files with no behavior summary.
• Humanize until ticket numbers change.
• Hide breaking changes in prose fluff.
• Use a humanizer to disguise AI-generated code you did not review.

Bottom line

PR descriptions win when why is obvious, tests are replayable, and risk is honest. Human Writes tightens summary prose after facts are locked.

Paste Why and Risk paragraphs on Human Writes after your test plan commands succeed locally.