To draft a pull request description with AI, freeze the base and head revisions, inspect the real diff, and prepare a verified input sheet before asking for prose. Require the draft to separate problem, scope, non-goals, behavior, tests, risks, rollout, and rollback. The author owns every statement and must update the description when new commits change the evidence.

This workflow improves review communication; it does not replace code review. The guide to using AI covers safe prompting, while AI for coding and reviewing AI-generated code cover implementation and verification.

Key Takeaways

Record exact base and head commits before summarizing.

Inspect the effective diff, including generated, configuration, migration, and test changes.

Give AI verified facts and actual command output, not assumptions.

Do not claim unrun tests passed or convert an inference into a security conclusion.

Make non-goals, risks, deployment order, and rollback limits visible.

Reconcile the description after every material commit.

What does the reviewer need to decide?

A pull request description should help a reviewer answer three questions: why is this change needed, what behavior and risk should I inspect, and what evidence supports merging it? A file-by-file paraphrase rarely answers them.

GitHub supports templates, required reviewers, ownership rules, draft pull requests, and other ways to standardize contribution and review.［1］ Standardization works when fields carry decision-relevant evidence, not when authors paste the same vague sentence into every section.

Write the acceptance criteria before drafting the description. Identify the user, operator, or developer outcome; expected behavior; important unchanged behavior; and failure conditions. If the criteria are still disputed, the PR description should say so rather than presenting a settled solution.

GitHub’s review guidance emphasizes providing context and clearly describing what a change does so reviewers can focus their effort.［2］ Treat reviewer attention as a limited resource. Lead with semantics and risk, then point to the relevant code.

Freeze base, head, and workspace state

Record the repository, target branch or base commit, head commit, and whether the description includes committed changes only or also a reviewed working-tree patch. Use immutable identifiers in your evidence notes even if the hosting interface displays branch names.

Confirm the comparison direction. A base-to-head diff answers what the proposed change introduces relative to its target. Comparing against the wrong base can include unrelated work or omit required context.

Check for generated files, submodules, lockfiles, migrations, configuration, schemas, and assets that ordinary source-focused review may miss. If the PR is stacked, state its dependency and which commits belong to this layer.

Never paste secrets, tokens, private keys, production data, sensitive logs, embargoed vulnerability details, or unrelated customer information into a model. Create a bounded evidence packet with only the material needed for the description.

What should you inspect before prompting AI?

Read the diff and trace behavior through entry points, callers, tests, and documentation. A renamed function may be mechanical; a one-line default may alter every request. File counts and diff size are not reliable impact measures.

Check whether the code implements the stated problem and whether the tests exercise that behavior. Inspect deleted code as carefully as added code. Review configuration defaults and rollout paths, because dormant code may not affect users until a flag or deployment step changes.

For APIs or persisted data, note compatibility, required migration order, retry behavior, and mixed-version operation. For user interfaces, describe the behavior and attach real interface evidence only when the PR actually changes UI. This article itself needs no screenshot and never treats a fabricated interface as evidence.

If you cannot determine the behavior from the available evidence, write Unknown in the input sheet. Do not ask AI to bridge the gap with a plausible story.

Build a verified input sheet

Use a structured source before generating paragraphs:

Field	Verified input	Evidence
Problem	`[observed problem and affected user]`	`[issue, reproduction, requirement]`
Scope	`[included behavior and components]`	`[diff paths and acceptance criteria]`
Non-goals	`[explicit exclusions]`	`[design decision]`
Behavioral change	`[before and after]`	`[test, contract, manual check]`
Components	`[services, packages, data, UI]`	`[diff inventory]`
Tests and actual output	`[command, environment, result]`	`[captured run]`
Risks	`[failure mode and exposure]`	`[analysis or test]`
Migration	`[order, compatibility, verification]`	`[migration plan]`
Rollout	`[flag, stages, monitoring, owner]`	`[release plan]`
Rollback	`[safe recovery and limits]`	`[tested procedure]`
Documentation	`[updated or not required, with reason]`	`[paths]`
Related issue	`[stable ID]`	`[tracker]`

Keep evidence precise. “Unit tests pass” should become “command completed on head [commit] in [environment]; [count] tests passed; [known exclusions].” If the output is too large, preserve it in an approved artifact and quote only the relevant summary.

Non-goals protect the review boundary. Examples include “does not migrate historical records,” “does not change the public schema,” or “does not enable the feature in production.” Verify each statement; a non-goal contradicted by the diff is a defect in the description.

Risks should name a failure mode, trigger, impact, mitigation, detection, and owner. “Low risk” is a conclusion, not evidence. If uncertainty remains, state it and direct reviewers to the relevant code or test.

Draft a pull request description with AI in a structured format

Provide the verified input sheet, selected diff excerpts or summaries, repository terminology, and the PR template. Limit the task to organization and wording.

A reusable prompt is:

Draft a pull request description using only the supplied input sheet and evidence. Preserve exact base/head identifiers, scope, non-goals, behavior, commands, outputs, risks, migration, rollout, rollback, documentation, and issue IDs. Do not claim unrun tests passed. Do not infer security, performance, compatibility, deployment, or user impact from filenames or diff size. Mark missing evidence Unknown and ask a reviewer question. Do not include secrets, sensitive logs, or non-public vulnerability details.

Ask for a claim ledger with the draft:

Claim ID	Draft statement	Evidence	Status	Reviewer focus
PR-01	`[bounded statement]`	T-02, D-04	Verified	`[path or behavior]`

Review the ledger before polishing prose. Remove any statement whose evidence does not support its full scope. A test for one error path does not prove overall reliability. A benchmark on a laptop does not prove production latency.

Use a reviewer-centered structure

A practical description is:

Problem: observed behavior, affected audience, and decision context.
Solution and scope: semantic approach and included components.
Non-goals: deliberate exclusions and follow-up boundaries.
Behavioral change: before, after, conditions, and compatibility.
Verification: actual commands, environments, outputs, and manual checks.
Risk and security: failure modes, trust boundaries, mitigations, and unknowns.
Migration, rollout, and rollback: order, owners, monitoring, and limits.
Documentation and related work: updated pages, issue, and dependent PRs.

Keep file-by-file details for sections where they help navigation. Link reviewers to the most important paths or commits, but explain why they matter. Do not bury a breaking change under a long implementation chronology.

Google’s engineering guidance argues that small, self-contained changes are easier to review and less likely to introduce defects.［3］ If the description requires several unrelated narratives, consider splitting the change. AI can improve organization, but it cannot make an incoherent scope easy to verify.

How do you report tests honestly?

Separate “run and passed,” “run and failed,” “not run,” and “not applicable.” Include the head revision and environment. If a command was interrupted, flaky, mocked, or unable to reach an external dependency, state that boundary.

Do not claim unrun tests passed. Do not copy green results from an earlier commit without rerunning relevant checks after behavior changes. A generated description may use confident past-tense language, so compare every verification sentence to captured output.

Explain why an important test was not run and what evidence remains. “Not run because this host lacks the required platform; required CI job is X” is more useful than omitting the gap. Local tests, CI, staging, and production observations are different evidence layers.

AI-assisted tests need normal review. The test-generation workflow can help propose cases, but only execution against the frozen head and semantic inspection establish useful evidence.

Describe risk without inventing assurance

Identify trust boundaries, authorization changes, sensitive data flows, external calls, background work, retries, and state transitions affected by the diff. Explain what the change preserves as well as what it changes.

Do not write “no security impact” merely because no security file changed. Conversely, do not claim a vulnerability or severity without validated evidence. State the reviewed boundary: “Authentication code is unchanged; this change modifies post-authentication formatting” is narrower and checkable.

NIST’s Generative AI Profile addresses confabulation, privacy, information integrity, and human oversight.［4］ For PR descriptions, the controls are minimal input, redaction, immutable revision IDs, claim-to-evidence mapping, and accountable review.

Handle private vulnerability information under the repository’s disclosure process. The public PR description may need a limited statement or a link accessible only to authorized reviewers. Never use AI to decide what can be disclosed.

How do you explain rollout and rollback realistically?

If the change is enabled immediately on merge, say so. If it depends on a feature flag, configuration, migration, package publication, or coordinated service order, name the exact prerequisite and owner.

Define monitoring in terms of observable signals and decision thresholds. “Monitor closely” is not a plan. State which metric, log, alert, or user report will be checked, for how long, and who can halt rollout.

Rollback must account for data and compatibility. Reverting code may not reverse a migration, external side effect, or emitted event. If rollback is unsafe, document forward recovery, isolation, or flag disablement instead of inventing a simple reversal.

Do not claim production verification in a pre-merge description. List the post-deployment checks as planned acceptance steps and update the record only after they occur in the correct environment.

Reconcile the draft against the diff

After AI drafts, read the description next to the exact diff. For each sentence, ask whether it is fact, inference, plan, or unknown. Facts need evidence; plans need owners; unknowns need a resolution path.

Run this checklist:

base and head identifiers are current;
problem and acceptance criteria match the issue and implementation;
scope includes every behaviorally relevant file;
non-goals are not contradicted by code or configuration;
before-and-after behavior is demonstrated;
tests quote real commands and actual output;
risks, migrations, rollout, and rollback are bounded and owned;
documentation status is accurate;
secrets and sensitive details are absent;
reviewer questions remain visible rather than guessed away.

The author owns the description. Reviewers may challenge it, but AI cannot accept responsibility for omissions, evidence quality, or repository policy.

What should you update after new commits?

A PR description is revision-bound. When new commits arrive, compare the old and new heads, identify which claims changed, and rerun affected tests. Update scope, risk, and rollout sections before requesting another review.

Do not regenerate blindly and lose reviewer context. Preserve still-valid explanations, clearly identify material changes, and answer resolved questions. If the scope expands substantially, consider a separate PR rather than stretching the original narrative.

Before merge, perform one final description-to-head check. After deployment, keep production verification in the appropriate release or operational record unless the repository explicitly uses the PR for that readback.

FAQ

Can AI read the diff and write the whole PR description?

It can draft from a bounded diff, but the author must trace behavior, provide actual test evidence, and review every claim. Diff text alone may not reveal runtime or deployment context.

Should I include every changed file?

No. Explain behavior and risk, then point to files that help review. A generated file list is not a substitute for semantic scope.

How should I report tests I did not run?

Label them “not run,” explain why, and identify the required environment or follow-up. Never imply success from an earlier revision or a different platform.

What belongs in PR non-goals?

List plausible expectations that the change deliberately does not satisfy. Verify that the diff truly preserves those boundaries.

Can AI assess PR security risk?

It can organize supplied evidence and questions. It should not invent a security conclusion, severity, or disclosure decision.

Should a PR description include screenshots?

Only when the change affects a visual interface and real evidence helps review. Use authentic captures from the correct revision and environment, with sensitive data removed.

What if the PR has a migration but no rollback?

State that limitation clearly and document the approved recovery or forward-fix path. Do not promise a code revert will undo data changes.

When must the description be updated?

After any commit that changes behavior, evidence, tests, risk, migration, rollout, or scope. Perform a final reconciliation against the merge candidate.

Sources

GitHub Docs, Managing and standardizing pull requests — https://docs.github.com/en/pull-requests/reference/managing-and-standardizing-pull-requests
GitHub Docs, Helping others review your changes — https://docs.github.com/en/pull-requests/concepts/helping-others-review-your-changes
Google Engineering Practices, Small CLs — https://google.github.io/eng-practices/review/developer/small-cls.html
National Institute of Standards and Technology, Artificial Intelligence Risk Management Framework: Generative Artificial Intelligence Profile — https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence

Sources checked 30 August 2026.

How to Draft a Pull Request Description with AI