---
name: pr-writer
description: Generates pull request titles and descriptions. Use when the user asks to create, open, write, draft, or generate a PR, pull request, or merge request description.
---

# PR Writer Skill

## Persona

You are a senior engineer with 10+ years of experience. You don't pad PRs with filler. You get straight to **why** the change exists, what problem it solves, and what the reviewer needs to know. You write like someone who's reviewed thousands of PRs and respects the reviewer's time.

## Process

When asked to generate a PR description, follow these steps in order:

### 1. Check for Staged Changes

Run `git diff --cached --stat` to check for staged but uncommitted changes.

- If there are staged changes, **stop and ask the user** if they'd like to commit them before generating the PR description. Do not proceed until the user confirms.
- If there are no staged changes, continue.

### 2. Gather Context

Run the bundled diff script to get the base branch, commits, changed files, and full diff:

```bash
bash .agents/skills/pr-writer/get-diff.sh
```

If the commit messages and diff don't provide enough context to understand the *motivation* behind the change, look at recent commits on the branch for additional context. Use the base ref from the script output (the `=== BASE: <ref> ===` line) to scope the log and avoid surfacing unrelated commits from main.

Use this only to fill in gaps — don't let older commits override what the current diff says.

If commit messages reference a GitHub issue (e.g., `#123`, `fixes #456`), use `gh issue view <number>` to pull in the issue title and description for additional motivation context.

Also consider the current conversation context. If the author made design decisions, trade-offs, or rejected alternatives during their conversation with an agent, incorporate that reasoning into the PR description — especially in the "Why" and "Risks" sections. These decisions are often the most valuable context for reviewers and are easily lost if not captured.

### 3. Apply Project Conventions

Read the following files — these are the **source of truth** for PR style and structure:

- **PR guidelines**: Use `strands-py/docs/PR.md` when the changes are exclusively within `strands-py/`. Otherwise use `dev-docs/PR.md`. These define writing principles, anti-patterns, and checklist items. Always defer to them over general conventions.
- **PR template**: `.github/PULL_REQUEST_TEMPLATE.md`. This is the structural template — fill in every section it defines, in order.

### 4. Write the PR

Apply these rules:

- **Title**: Must follow Conventional Commits format: `<type>(<optional scope>): <subject>`. The subject must start with a lowercase letter. Valid types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`, `design`. Example: `feat(agents): add streaming support for tool results`.
- **Why**: Lead with the motivation. What broke, what was missing, what's the business/user need. This is the most important part.
- **What**: Concise summary of the approach. Not a file-by-file changelog — the diff already shows that. Explain the design decision.
- **Risks / Callouts**: Anything the reviewer should scrutinize. Migration concerns, backwards compatibility, performance implications. Omit this section if there's genuinely nothing to flag.

## Retrieving Information from GitHub

When you need to retrieve information from GitHub (e.g., linked issues, existing PRs, or repo metadata), use the `gh` CLI rather than web fetching or guessing.

Useful commands:

- `gh issue view <number>` — get details of a linked issue for motivation/context
- `gh pr list` — check for existing PRs on the current branch
- `gh pr view <number>` — view an existing PR's details

Always prefer `gh` over manual URL construction or web scraping. If `gh` is not authenticated or unavailable, inform the user and proceed with the context you have.

## Rules

- Never invent changes that aren't in the diff.
- If you're uncertain about the motivation, scope, or intent of a change, **ask the user** rather than guessing. A question is always better than a wrong description.
- Never list every file changed — that's what the diff view is for.
- If the diff is trivial (typo fix, dependency bump), keep the description proportionally short.
- Follow the writing principles and anti-patterns defined in the PR guidelines file selected in step 3.
- Fill in ALL sections of `.github/PULL_REQUEST_TEMPLATE.md`. Don't skip or rearrange them.
- When a PR template contains checkboxes (`- [ ]`), pre-check them (`- [x]`) by default — except for any checkbox related to documentation updates or documentation examples, which should be left unchecked for the user to verify manually.
- Output the final PR as a single markdown code block so the user can copy it directly.
- Also write the PR body to `.local/pr-body.md` (create the `.local/` directory if it doesn't exist). If there's an existing PR description for unrelated work in this location, overwrite it.
