---
name: pull-request-description-writer
description: "Writes a pull request description with a summary, before and after evidence, test steps and an honest call on how dangerous the merge is. Use when a pull request is ready to open and needs a clear body with evidence, test steps and a risk call. Do not use for asking a reviewer to look at specific code or writing release notes. Related topics: coding, communication."
---

# Pull Request Description Writer

Writes a pull request description with a summary, before and after evidence, test steps and an honest call on how dangerous the merge is.

## When to use

Use this skill when a pull request is ready to open and needs a clear body with evidence, test steps and a risk call. Do not use it for asking a reviewer to look at specific code or writing release notes.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Write a title that states the effect and a two or three sentence summary of problem and fix.
3. Present before and after evidence exactly as supplied, without describing results that were not given.
4. List the notable changes by area and leave out trivial edits.
5. Write numbered test steps with an expected result for each.
6. Close with a low, medium or high merge-danger call, the reasons and a rollback plan.

## Inputs

- **What changed** (longer free text)
- **Why** (longer free text)
- **Before and after evidence** (longer free text)
- **How to test** (longer free text)
- **Linked issue** (free text, e.g. "Issue number or link")
- **Breaking or risky parts** (longer free text)

## Output

A pull request body with title, summary, before and after, change bullets, numbered test steps, merge-danger call with rollback plan and the issue link.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Pull Request Description Writer

Write the description for this pull request.

- What changed: {{What changed}}
- Why: {{Why}}
- Before and after evidence: {{Before and after evidence}}
- How to test: {{How to test}}
- Linked issue: {{Linked issue}}
- Breaking or risky parts: {{Breaking or risky parts}}

Open with a title that states the effect in under 70 characters, then a summary of two or three sentences covering the problem and the fix. Add a before and after section showing evidence rather than describing it. List the notable changes as short bullets grouped by area, skipping trivial edits. Give test steps as a numbered list a stranger could run, including the expected result of each step. End with a merge-danger call of low, medium or high, and state why: data migrations, public interface changes, config or deploy ordering, and anything hard to roll back, along with the rollback plan. Link the issue. Do not claim tests pass unless the input says so.

## Pitfalls

- Describing the diff line by line instead of the effect, which repeats what the reviewer can already see.
- Test steps that skip the setup, so the reviewer cannot reproduce them.
- Rating the merge low-risk while a migration is part of it.