GitHub Copilot PR Summary: How to Get Descriptions Reviewers Actually Read

A GitHub Copilot PR summary reads your diff and drafts the pull request description for you. Left on its default, it restates the diff, which the reviewer can already read. The summary a reviewer actually reads answers what the diff cannot: why the change exists, what could break, and where to look first. This is how to get that one, shown on a pull request whose description said “fixes stuff”.

Picture a pull request on the MSDevBuild Eats food delivery app titled “refactor cart pricing”. The description says “fixes stuff”. The diff touches eleven files: pricing moves from the cart widget into PricingPolicy, a few names change, tests are updated. Buried in the middle, one line renames a field in the cart’s saved JSON, the cart_state key in shared_preferences.

The reviewer spends forty minutes reverse-engineering the intent, reviews the pricing move carefully, and approves. The JSON rename goes through. Testers on the previous build open the app and their saved cart fails to load, and rolling the web build back does not help: the new data is already on their phones.

A Copilot summary on default would have described that pull request as “refactored cart pricing and updated the cart model”. True, and no help to the reviewer.

If Skills and custom instructions are new to you, start with why Copilot Skills exist. Read this alongside the limits of AI code review; a good summary and a good review are two halves of the same handoff.

One afternoon, one line nobody was told about

The commands that would have found the risk

The app’s pull request template names the three things a rollback cannot undo. You can check a branch for all three before anyone reviews it:

# How big is it?
git diff --stat main...refactor/cart-pricing | tail -1

# Anything touching the saved cart's shape?
git diff main...refactor/cart-pricing -- lib | grep -nE "kCart|cart_state|toJson|fromJson"

# Security rules or the order status machine?
git diff --name-only main...refactor/cart-pricing | grep -E "firestore.rules|storage.rules|order.dart|pricing_policy"

On the scenario branch:

Four lines out of several hundred, and they were the only ones that mattered. A description that said “Risk: the cart_state JSON shape changes; old builds will not read it” would have sent the reviewer there first.

If you would rather see the idea first, it is a short video:

Who is a PR description actually for?

The reframe that changes everything: A pull request description is not written for the author. The author already knows what they did. It is written for two other people:

1. The reviewer, right now, who has to decide whether this is safe to merge.
2. Future-you, a year from now, staring at git blame on a line that just caused an incident, trying to remember why it exists.

Neither of them can read your mind. Both of them can already read the diff. So the description has exactly one job: add everything the diff cannot say.

A good PR description answers five things, and only the first is in the diff:

Look at that table for a second. The diff, and therefore the AI, owns exactly one row. The four rows that decide whether a review goes well are all things only a human knows. That is not a limitation of Copilot. That is the shape of the problem.

In short: the diff shows what. The description exists to add why, risk, test evidence, and where to look. An AI summary that only does “what” has restated the diff.

What the GitHub Copilot PR summary does today

To be accurate about the current feature, because it moves fast: On github.com, when you open or edit a pull request, you click into the description field, select the Copilot icon in the toolbar, and choose Summary. Copilot reads the diff and generates a prose overview of the change plus a bulleted list of what changed, with the files each bullet touches. There is also a “pull request assistant” style experience in the IDE and in Visual Studio that drafts the description from your commits and diff.

A few honest details that matter in practice:

• It is not in the Copilot Free tier. You need a paid Copilot license.
• It works best from a blank description field. Historically it ignores text you have already typed, so half-filling a template and then hitting Summary can wipe or override your work. Draft first, then edit.
• It reads the diff and changed files. That is its entire world. It does not read your Jira ticket, your incident history, your Slack thread, or the rollback plan in your head.

That last point is the whole story. Because the AI only sees the diff, its default output is a very fluent restatement of the diff. It will tell you a CalculateRefund method was added and OrdersController was modified. Both true. Both already visible one tab over. This is the failure mode I want you to design around.

The core problem: a summary that restates the diff is noise

I need to be blunt here, because the marketing around this feature never is. An auto-generated summary that parrots the diff does not save review time. It costs it. Now the reviewer reads a paragraph of prose and the diff, and the prose added nothing. Worse, fluent prose creates false confidence. It looks like context, so people skim it and assume the risky part was covered when it never was. That is precisely how the reviewer nearly missed the migration.

The fix is not to abandon the AI. It is to change what the AI is drafting into. If you give Copilot a structured target (a template with the right sections and instructions to fill them), the generated draft stops being a diff echo and starts being a real first draft that a human finishes. Let me show you the machinery.

The PR template that forces the right content

The single most effective thing you can commit today is a pull request template. Drop this file in your repo at .github/pull_request_template.md and every new PR opens pre-loaded with these sections. It costs nothing and it changes behaviour immediately, because an empty section is an obvious, embarrassing gap that people fill in.

<!-- .github/pull_request_template.md -->

## Summary
<!-- What does this PR do, in one or two plain sentences? -->

## Why
<!-- Why is this change needed? Link the ticket or incident.
     This is the part the diff can NOT tell the reviewer. -->
Closes #

## Changes
<!-- The key changes. The AI-generated summary can draft this section. -->

## Risk & rollback
<!-- What is the blast radius? Any migration, data change, feature flag,
     or breaking API change? How do we roll back if this goes wrong? -->

## Testing
<!-- How was this verified? Unit tests, manual steps, screenshots.
     "Trust me" is not testing. -->

## Reviewer focus
<!-- Where should the reviewer spend their attention?
     e.g. "Look hard at the migration in OrdersDbContext." -->

Notice what the template does. It makes “Why”, “Risk & rollback”, and “Reviewer focus” mandatory-looking. It puts Closes # right where the author has to type a ticket number. And it explicitly hands the “Changes” section to the AI, so the human effort goes where the human is irreplaceable. The template is the contract. The AI fills one clause of it.

One production note from experience: keep this template short. I have seen teams build a fourteen-section template with checkboxes for accessibility, i18n, telemetry, and six other concerns. Everyone ticks every box without reading. A template that demands too much gets satisfied dishonestly. Six sections people actually complete beat fourteen they rubber-stamp.

Steering Copilot with custom instructions

The template shapes the human. Custom instructions shape the AI. If your team uses repository custom instructions (the same mechanism covered in Copilot custom instructions), you can tell Copilot how to write the summary so its draft lands in the right shape instead of as a diff dump.

An instruction block that works: It goes in your repo-level Copilot instructions:

# PR summary guidance for Copilot

When drafting a pull request description:

- Follow the structure in .github/pull_request_template.md.
- Write the "Changes" section as a short, grouped list of what changed
  and why each group of changes was made — not a file-by-file diff dump.
- Do NOT restate the obvious. "Modified OrdersController" tells the
  reviewer nothing they cannot see in the diff.
- Flag anything that looks risky in its own line: database migrations,
  schema changes, deleted endpoints, changed public method signatures,
  new external calls, changes to auth or money calculations.
- Leave the "Why", "Risk & rollback", and "Reviewer focus" sections
  for the author to complete. Add a "[author: fill this in]" marker.
- Never invent a reason for the change. If the intent is not clear
  from the diff, say so instead of guessing.

Two lines in there do most of the work. “Flag anything that looks risky in its own line” is what would have surfaced the reviewer’s migration instead of hiding it in a bullet. And “Never invent a reason” is the guardrail against the AI’s worst habit: writing a confident, plausible, wrong explanation of why you made a change. I will come back to that.

A caveat: how strictly Copilot honours your template and instructions is still improving, and there is active community discussion about it. Treat the generated draft as a starting point, not a finished artifact. The point is not perfect obedience. The point is a better first draft.

Bad summary vs good summary: the same PR

To make this concrete, take an orders change: adding a refund calculation. Same diff, two descriptions.

What the default AI summary tends to produce:

## Summary
This pull request adds refund calculation to the Orders service.

## Changes
- Added CalculateRefund method to OrderService
- Modified OrdersController to expose a new POST /orders/{id}/refund endpoint
- Added RefundRequest and RefundResult models
- Updated OrdersDbContext
- Added RefundServiceTests

Read it as the reviewer would. Every line is true. Every line is already in the diff. And the one thing that will hurt in production, “Updated OrdersDbContext”, is sitting quietly in the middle, giving no hint that it is a migration that changes a stored column. This summary passed the effort test and failed the reviewer.

And the version where the AI drafted the “Changes” and the author did their two minutes of irreplaceable work:

## Summary
Adds a refund endpoint so support can issue partial refunds without a DB script.

## Why
Support has been running manual SQL to refund customers since launch (see
INC-2291). This closes that hole. Closes #874.

## Changes
- New POST /orders/{id}/refund endpoint and RefundRequest/RefundResult models.
- CalculateRefund refunds the amount the customer actually PAID
  (post-discount), not the pre-discount total — this was the bug in INC-2291.
- Migration on OrdersDbContext: adds a nullable RefundedAmount column.

## Risk & rollback
- Contains a DB migration (nullable column, additive — safe to roll forward).
- Touches money. If the calculation is wrong we over- or under-refund
  real customers. Rollback: revert the deploy; the column can stay, it is nullable.

## Testing
- Unit tests cover full refund, partial refund, and the post-discount case
  from INC-2291.
- Manually tested against a staging order with a 15% discount applied.

## Reviewer focus
- Please check CalculateRefund against the INC-2291 scenario specifically.
- Confirm the migration is additive and won't lock the table on deploy.

The second one is not longer for the sake of it. Every extra line is a thing the diff could not say. The migration is announced, not hidden. The money risk is stated. The exact scenario to scrutinise is named. the reviewer now starts his review from context, not from confusion. The AI wrote maybe half of that. The half that saved the afternoon was the author’s.

The efficiency payoff, and how it ties to review

This is where the summary and AI-assisted review meet. When the description carries the why and the risk, the reviewer’s attention shifts from decoding to judging. That is the entire point of a review: human judgment. A bad description wastes it on archaeology.

The workflow shift, before and after:

BEFORE (empty or diff-restatement description)
Author: opens PR, writes "fixes stuff"
   -> Reviewer: reads diff cold
   -> Reviewer: guesses intent, opens the ticket, pings the author on Slack
   -> Author (3 hours later, different time zone): answers
   -> Reviewer: re-reads, finally reviews the actual design
   -> ~40 min of reviewer time, most of it spent reconstructing context

AFTER (AI-drafted + author-supplied why/risk)
Author: opens PR, hits Summary, fills Why + Risk + Focus (2 min)
   -> Reviewer: reads a description that answers the questions up front
   -> Reviewer: goes straight to the flagged migration and the money math
   -> ~10 min, spent on judgment, not archaeology

For a team split across time zones, that chat round-trip in the “before” flow is not three minutes. It is often the next working day. A good description is what keeps an async team from blocking on a question the description should have answered. That, plus cleaner git history and honest changelogs, is the real return. Not “AI writes my PRs for me.” Better handoffs between humans.

Where the AI still gets it wrong

I would be doing exactly the thing I criticise in AI hype if I did not lay out the limits plainly. Where a Copilot PR summary fails, from real use:

• It restates the diff and calls it a summary. The default output describes what and skips why. On its own it is often net-negative for review time.
• It hallucinates the “why”. The single most dangerous failure. The AI cannot know your intent, so if you let it, it writes a confident, plausible, wrong reason for the change. A reviewer who trusts that reason reviews against the wrong goal.
• It buries the risky change. Without instruction, a migration or a saved-data shape change gets one bullet among ten routine ones, exactly like the cart refactor.
• It cannot assess risk. It does not know that this table has 40 million rows, that this endpoint is on the checkout path, or that a similar change caused last quarter’s incident. Risk needs context the diff does not carry.
• It has no rollback plan. Rollback is an operational decision, not a code fact. The AI has nothing to draw on.
• It can leak sensitive detail. If a secret, a customer identifier, or an internal URL is in the diff, the summary can surface it into a description that is more visible and more copy-pasted than the diff itself.

None of these are reasons to switch the feature off. They are the map of which parts the human must own.

Rolling this out on a team

You do not adopt this by telling people to “write better PRs”. You adopt it by changing the defaults. The order to do it in:

1. Commit the PR template. Add .github/pull_request_template.md with Summary / Why / Changes / Risk & rollback / Testing / Reviewer focus. This alone lifts the floor for every PR, with or without Copilot.
2. Commit the custom instructions. Add the Copilot instruction block so generated summaries target your template and flag risky changes instead of restating the diff.
3. Make the culture rule explicit. The author owns the why. The AI drafts the what. Write that sentence down somewhere the team sees it. Tools do not create the norm; the team does.
4. Optionally, add a CI gate. A lightweight check that fails a PR whose description is empty or still all template comments. Do not over-tune it. The goal is to catch “fixes stuff”, not to police prose.
5. Pair it with the AI review setup. The AI review runs the mechanical checklist; the good description points the human reviewer at the judgment call. Together they cover both layers.

Step 3 is the one teams skip, and it is the one that matters most. I have watched a perfect template fill up with [author: fill this in] markers that nobody replaced, because nobody agreed the author was on the hook for them.

Do’s and don’ts

How efficient is a good description?

The author spends about two minutes on the why, the risk and the focus. The reviewer gets most of their first half hour back, and it goes to judgment instead of archaeology.

The rule underneath: two minutes of the author’s context saves the reviewer’s first half hour, because the author is the only person who already knows why.

Questions a tech lead will ask about this

1. “Can Copilot write the whole description?” It can write the changes section. It cannot know why the change exists or what a rollback cannot undo, and if you let it, it will guess.
2. “Won’t people leave the template markers in?” Some will. A small CI check that fails a pull request whose description is empty or still all template comments catches it.
3. “How long should the description be?” As short as the six sections allow. Most are ten lines.
4. “Who is responsible if the description is wrong?” The author. The AI drafts; the author signs.
5. “What goes in Reviewer focus?” The one or two files where a mistake is expensive, named. The cart refactor’s answer was one file.

What to do on day one

• Commit .github/pull_request_template.md with Summary, Why, Changes, Risk & rollback, Testing and Reviewer focus.
• Name your app’s own un-rollback-able changes in the Risk prompt, the way the food delivery app names shared_preferences.
• Add the PR summary guidance block to copilot-instructions.md.
• Agree, out loud, that the author owns the why.
• Run the risk grep on your own branches before you ask for review.

Key takeaways

• A Copilot PR summary on default restates the diff; the reviewer can already read the diff.
• The description earns its place with what the diff cannot say: why, risk, rollback and focus.
• Copilot drafts the changes; the author writes the why and signs the risk.
• A committed template plus summary instructions change the default for the whole team.
• Name the changes a rollback cannot undo, and check branches for them before review.

The next cart change

A month later, the same developer changes how the cart stores applied promos. Copilot drafts the Changes section, grouped by layer. The author writes two lines by hand:

“Why: promos need an expiry so stale codes stop applying. Risk: the cart_state JSON gains a field; old builds ignore it, and a migration fills it for existing carts. Reviewer focus: cart_repository_impl.dart, the migration.”

The reviewer opens that file first, reads the migration, asks one question about a null expiry, and approves in twelve minutes. Nobody’s cart disappears.

Test yourself: answer in the comments

(These Copilot features change quickly. The exact buttons, tiers and behaviour above were current when written; check the GitHub Copilot documentation for what is live when you read this.)

Sources:

• Creating a pull request summary with GitHub Copilot — GitHub Docs
• Let GitHub Copilot draft your pull request description — Visual Studio Blog