AI Commit Messages and PR Descriptions Reviewers Trust

A useful commit message explains a change without asking the reader to reconstruct an entire conversation. A useful pull request description helps someone review that change independently. AI can draft both, but only when it receives the actual diff and enough context to distinguish implemented behaviour from intended behaviour.

The main risk is confident invention: tests described as passing when nobody ran them, performance improvements inferred from shorter code, or a rollout plan copied from an unrelated task. Build the writing workflow around evidence and the resulting summaries become faster to prepare without becoming less trustworthy.

Start with the exact review boundary

Choose the comparison boundary before generating a summary. For a commit message, inspect the changes staged for that commit. For a pull request, compare the branch against the intended base and account for the complete set of included commits. An assistant looking only at the last file edited may miss a migration or configuration change added earlier.

Check the diff yourself for generated files, accidental formatting churn, unrelated edits and sensitive material before sharing it with a model. Repository content may be private even when it contains no credentials. Follow your team's approved tooling and data-handling policy rather than uploading a patch to an arbitrary writing service.

Use the Git documentation to confirm the commands that inspect staged changes and compare branches. The precise command depends on your workflow, but the principle is stable: the assistant should describe the same review surface the human reviewer will see.

Supply the issue or acceptance criteria as context, not as proof of completion. A ticket saying “add retry support” does not establish that retries were implemented correctly. Ask the assistant to reconcile the request with the diff and flag any discrepancy instead of repeating the ticket as a success statement.

Write commits around one coherent change

A good commit message identifies the behavioural change and, when necessary, its reason. “Handle an expired session before retrying an upload” tells a future maintainer more than “improve upload logic.” Avoid sweeping claims such as “optimise performance” unless there is evidence of the specific improvement.

If the staged patch combines unrelated work, split it before asking AI to produce a tidy sentence. Language cannot repair an incoherent commit boundary. A refactor, a feature and a generated dependency update may deserve separate commits even if they emerged from one assistant session.

Follow the repository's existing convention. If it uses Conventional Commits, provide the expected type and scope vocabulary rather than asking the model to invent categories. Conventional formatting is useful for tooling, but a syntactically valid prefix does not make the description accurate.

Use the body for decision context that is not obvious from the patch: a compatibility constraint, an upstream limitation or why an apparently simpler approach was rejected. Do not narrate every changed line. Keep speculative future work separate from what this commit actually establishes.

Separate implementation from verification

A pull request needs a concise summary, review guidance, observed checks and relevant operational notes. The GitHub documentation on pull requests describes the collaboration workflow; your description should make that workflow easier rather than become a second, less reliable issue tracker.

Give the assistant verification evidence explicitly. Include the exact commands run, their outcomes, the environment and any limitations. If a command could not run because a service was unavailable, report that as a blocker. Do not let the draft translate “test added” into “test passed.”

A useful prompt makes that distinction non-negotiable:

Draft a pull request description from this base-to-branch diff.
Use sections: Summary, Review focus, Verification, Rollout and risks.
Describe implemented changes only; flag unmet ticket requirements.
List only checks present in the supplied execution record as completed.
Do not infer performance, accessibility or security improvements.
Mark missing verification as not run and explain the known reason.
Keep the description concise enough to scan before opening the diff.

For a change to a publicly reachable API endpoint, use the API latency tester to collect a small observational timing sample and record the endpoint, time and conditions alongside the result. Do not include credentials or sensitive query parameters. Such a sample is not a load test, a service-level guarantee or proof that the patch caused a performance improvement.

Give reviewers a map, not a sales pitch

Identify review hotspots: permission checks, data migrations, error handling, compatibility boundaries and surprising trade-offs. Link those notes to relevant files or functions using your hosting platform's supported references. A reviewer should know where a mistake would matter most without being told what conclusion to reach.

Describe user-visible states, not just implementation mechanics. If a request can now time out, explain what the user sees and whether retrying is safe. If a schema changes, state how existing data and older clients behave. These details help reviewers choose meaningful scenarios rather than merely checking style.

Keep the tone neutral. “This guarantees robust security” is a warning sign, not useful review guidance. Replace it with the actual control and its evidence: the server checks resource ownership, and a named test covers an unauthorised request. The workflow in security risks in AI-written code helps identify claims that deserve closer inspection.

Include known limitations without minimising them. An unsupported browser, an untested migration path or a temporary manual step belongs in the description when it affects acceptance or release. Do not conceal unfinished work in vague wording such as “additional edge cases can be considered later.” State what remains and who will decide whether it blocks merging.

Refresh the description before handoff

Generated descriptions go stale as soon as the patch changes. After review fixes, inspect the final diff and update the summary, verification record and rollout notes. A removed dependency or abandoned approach should not remain in the description simply because it appeared in the first draft.

Make rollout and reversal proportional to risk. A copy edit may need no operational plan. A background-job change may require a staged release, monitoring and a specific rollback constraint. If reversing code cannot reverse a data migration, say so explicitly and refer to the approved recovery procedure.

The project instructions guide can help encode reporting expectations, while the AI coding assistants directory provides a starting point for comparing drafting tools. Keep the evidence format portable so a change of editor does not change what reviewers can trust.

Review the final text as carefully as the patch. Remove invented issue links, unsupported metrics, exaggerated adjectives and statements that confuse intent with observation. Ensure commands and outcomes correspond to the latest revision; otherwise label which revision was actually tested.

Finally, take responsibility for the description you publish. The reviewer should not need to know which sentences came from an assistant. They should be able to rely on every completed check, understand every disclosed uncertainty and navigate directly to the consequential parts of the change.

Key takeaways

• Generate summaries from the exact staged patch or pull request comparison.
• Keep commits coherent and describe behaviour rather than vague improvement.
• Separate tests added, tests executed and checks blocked by the environment.
• Highlight review hotspots, compatibility risks and genuine limitations.
• Refresh the description after edits and verify every published claim.