Pull request descriptions are one of the most routinely neglected parts of a development workflow. Under deadline pressure, it is easy to type "fixes the bug" and move on. But a well-written PR description saves review time, accelerates approval, and creates a permanent record of why code changed — not just what changed. AI can produce a solid first draft in seconds, given the right input.

## What Makes a Great PR Description

A useful PR description covers:

- **Context** — what problem does this solve, and why now?
- **What changed** — a scannable summary of the work done
- **How to test it** — specific steps a reviewer can follow to verify the change works
- **Screenshots or links** — essential when UI has changed
- **Breaking changes or migration notes** — anything that affects other teams
- **Issue or ticket references** — so reviewers can trace back to the original requirement

## Getting the Right Input for AI

```bash
# High-level narrative of work done
git log main..HEAD --oneline

# Files changed overview
git diff main..HEAD --stat

# Full diff for detailed descriptions
git diff main..HEAD
```

The `--oneline` output gives a high-level narrative. The `--stat` output shows which files were touched. Together they let AI summarise the scope without reading every line.

## Writing PR Descriptions with AI Tools

### GitHub Copilot

GitHub includes a "Generate with Copilot" button directly on the PR description field at GitHub.com. Click it after pushing your branch and Copilot reads your diff and generates a description automatically. Always edit the output before publishing — the raw draft is a starting point, not a finished product.

### In the Terminal with Claude or ChatGPT

```bash
# Copy full diff to clipboard (macOS)
git diff main..HEAD | pbcopy
```

Then send a prompt like:

> "Write a GitHub pull request description for this diff. Include: what changed and why, how to test it, and any breaking changes."

### Cursor

In the Cursor chat panel, paste your `git log --oneline` output alongside a prompt asking for a PR description. Cursor's codebase awareness supplements the diff with context about the files involved.

## Prompting AI for Different PR Types

Tailor your request to the type of change:

- **Bug fix** — "Emphasise the root cause, what was broken, and how this change fixes it."
- **Feature** — "Focus on user impact, what is new, and how to test it end-to-end."
- **Refactor** — "Explain what was simplified and confirm that behaviour has not changed."
- **Breaking change** — "Highlight migration steps prominently at the top."

## Using a PR Template

Add `.github/pull_request_template.md` to your repository and GitHub will pre-populate the description field on every new PR:

```markdown
## What does this PR do?

## Why are we making this change?

## How to test

## Breaking changes
None / [describe]

## Related issues
Closes #
```

To use AI with this template, paste both the template and your git diff into your AI tool, then prompt:

> "Fill in this PR template based on the diff below. Be concise and specific."

AI fills in templates reliably and consistently — it removes the friction of starting with a blank box and enforces structure without requiring anyone to police it.

## Editing the AI Output

AI-generated PR descriptions tend to be verbose. Before publishing, trim:

- Filler openers ("This PR introduces...", "In this pull request...")
- Overly detailed technical descriptions that belong in code comments
- Inflated importance of minor changes

And add back what AI cannot know:

- Specific issue or ticket numbers
- Business context behind the decision
- Test steps accurate to your actual environment

## DeployHQ and Your Deployment Workflow

At [DeployHQ](https://deployhq.com), you can trigger deployments directly from branches or pull requests, making the PR the natural checkpoint before code reaches production. A clear, well-written PR description means faster approval and a faster path to deployment. When reviewers understand what changed and why, review cycles shrink and deployment confidence goes up.