---
name: create-pr
description: Patterns and conventions for creating a good PR
---

# PR Description Guidelines

The work is done. Now, create a new PR for the current changes. If you're not on a new branch yet, create one first. Then, create the PR.
Treat the changes as a real deliverable. The description is the first thing anyone reading this work will see, and most readers will not read the diff line by line.

## Audience

Write for someone who:
- Is a developer on this team
- Already knows this repository and its existing architecture
- Has not seen this work before

You don't need to explain the codebase, the framework, or how things generally work in this system. You do need to explain everything *new* that this PR introduces — concepts, entities, flows, behaviors — clearly enough that the reader understands the change without opening the diff.

Cover only what's in *this* PR. If it's part of a larger effort (MVP, migration, refactor), one short line of framing is enough. Don't restate the whole project.

## Title

The title is a one-line summary of the change. Specific, declarative, imperative mood.

- Good: `Add alert incident lifecycle and worker pipeline`
- Bad: `Alert work` / `Various improvements` / `Updates to alerts module`

If the repo uses a prefix convention (`feat:`, `fix:`, scoping like `[backend]`), match it.

## What the description must convey

Every PR description, regardless of size, has to answer:

1. **What this PR does** — the actual change, in plain language
2. **Why it exists** — the problem, motivation, or unblock (skip only if the title makes it self-evident)

Beyond those two, include whatever else the reader needs to actually understand the change:

- New domain concepts introduced (entities, events, jobs, statuses, etc.): what they are, when they're created, who produces and consumes them
- Non-obvious decisions: trade-offs, why an alternative was rejected, schema or concurrency choices that aren't visible from the diff
- Deliberate scope cuts and known follow-ups
- Anything a reviewer would otherwise have to reverse-engineer from the code
- How the change was tested or validated, when relevant

If something is only interesting at the code level — naming, file moves, mechanical refactors — leave it in the diff.

## Structure

Don't follow a fixed template. The right structure depends entirely on what this PR contains.

Decide the structure by asking: *what does the reader need to know, and in what order?* Then group that information into coherent sections with headers that describe their actual content. A small bug fix might be three sentences with no headers at all. A PR introducing a new subsystem might have five sections. Both are correct when they match the change.

Order matters: start with whatever orients the reader fastest (usually a summary), put context next, push edge cases, caveats, and follow-ups toward the end.

## Linking

If related issues or PRs exist, link them. Use GitHub's keyword syntax (`Closes #123`, `Refs #456`) where appropriate.

## Style

The description should read like a senior engineer wrote it for a colleague — direct, specific, no filler. The following phrasings mark text as AI-generated and must be avoided:

- **Marketing adjectives**: "comprehensive," "robust," "seamless," "powerful," "elegant," "sophisticated," "production-ready," "first-class"
- **Hedging verbs**: "aims to," "seeks to," "strives to" — just say what it does
- **Filler verbs**: "leverages" / "utilizes" → "uses". "ensures that X" → just state X. "facilitates" → describe the actual mechanism
- **Throat-clearing openers**: "It's worth noting that," "Importantly,", "In essence,", "It should be mentioned that"
- **Closing summaries**: "In summary," "Overall," "Ultimately," — stop when you're done
- **Vague abstractions**: "provides functionality for X" → say what it does. "handles the logic of Y" → say how
- **Artificial parallelism**: "fast, clean, and reliable" — pick the one that matters
- **"Not just X but Y" construction**
- **"In order to"** → "to"
- **Restating the prompt or the section header in the first sentence of a section**

Write declaratively. "Adds X. X is created when Y happens." Not "This PR aims to introduce X, which would help with Y."

Use prose where bullets would fragment a thought. Use bullets where prose would become a wall. Don't enumerate every file changed.

Use lowercase headings unless the repo's existing PRs use a different convention.

## Output

Return the title and description as raw markdown in separate code blocks I can paste into GitHub directly. No preamble, no commentary after the blocks.

If this PR includes noticeable UI work — new views, new sections, visual changes — remind me at the end to attach screenshots or a short screen recording to the PR for reviewer context.