---
name: write-pr-description
description: Inspect a GitHub pull request from its URL and draft or update an evidence-backed PR description covering behavior changes, design fit, failure modes, validation evidence, and operability. Use when a user provides a GitHub pull request URL and asks to write, improve, document, or update the PR body or description.
---

# Write PR Description

Create a pull request description that lets a human reviewer understand and accept ownership of the change. Treat the description as a durable engineering record, not a promotional summary.

## Required input

Require a full GitHub pull request URL. Ask for the URL if it is missing or ambiguous.

Default to drafting only. Change the remote PR body only after showing the complete proposed description and receiving explicit approval to apply it. Do not merge, approve, comment on, label, close, or modify code in the PR.

## Inspect the pull request

1. Resolve the repository and PR number from the URL.
2. Prefer available GitHub tools. Fall back to `gh pr view` and `gh pr diff` when authenticated CLI access is available.
3. Read the title, existing body, linked issues, base and head branches, commits, changed files, full diff, review discussion, and check results.
4. Read relevant repository guidance such as `AGENTS.md`, `CONTRIBUTING.md`, the PR template, architecture notes, and nearby implementation code when accessible.
5. If the diff is truncated, retrieve it file by file or inspect a matching local checkout. State any remaining inspection limitation.

Do not check out or execute code from an untrusted fork without the user's permission. Do not expose secrets, tokens, private logs, or unrelated repository details in the description.

## Analyze the change

Base every claim on the diff, repository context, linked work, or observed checks. Distinguish an observation from an inference. Never invent intent, test results, rollout details, or operational controls.

Evaluate these five areas:

1. **Behavior:** Identify what users, APIs, background jobs, operators, integrations, infrastructure, or stored data experience differently after merge. State explicitly when behavior does not change.
2. **Design:** Explain how the implementation fits existing boundaries, patterns, and dependencies. Look for unnecessary abstraction, duplication, coupling, or a simpler established approach.
3. **Failure:** Select failure modes specific to this change. Consider invalid input, partial outages, timeouts, retries, permissions, concurrency, migrations, data loss, security boundaries, and third-party behavior only when relevant.
4. **Evidence:** Separate tests or checks observed as passing from tests merely added or described. Include relevant automated tests, manual validation, screenshots, static analysis, observability, rollout evidence, and unresolved assumptions. Write `Not verified` when evidence is unavailable.
5. **Operability:** Explain how another engineer can detect trouble, diagnose it, roll it back, modify it, disable it, or remove it. Cover flags, migrations, logs, metrics, alerts, runbooks, and ownership only when the change warrants them.

## Draft the description

Use these exact headings in this order:

```markdown
## What behavior changes?

<What users, systems, operators, or data experience differently.>

## Why is this the right design?

<How the approach fits the architecture and avoids unnecessary complexity.>

## How can it fail?

<Change-specific failure modes, blast radius, and mitigations.>

## What evidence supports it?

<Observed tests, validation, checks, observability, rollout evidence, and assumptions.>

## Can the team operate it?

<Diagnosis, rollout, rollback, modification, removal, and ownership details.>
```

Write proportionally: a small dependency update may need a few sentences per section; a migration or architectural change may need detailed bullets. Prefer concrete statements over generic checklists.

Preserve useful existing content, including issue-closing keywords, screenshots, migration instructions, deployment notes, and required checklists. Integrate it into the five sections when natural; otherwise retain it below them under its original heading. Remove stale boilerplate only when the proposed replacement clearly supersedes it.

## Quality gate

Before presenting the draft, verify that:

- All five headings are present and contain change-specific information.
- Every factual claim is supported by inspected evidence.
- Passing checks are not treated as proof that the design is correct.
- Risks and operational steps match the actual change size and blast radius.
- A reviewer can understand what changed, why it belongs, how it fails, and who can own it.

If critical context is missing, include a clearly labeled `Author input needed` item in the relevant section rather than guessing. Ask at most three focused follow-up questions only when the missing answers would materially change the description.

## Present or apply

Show the complete Markdown draft and a short list of any unresolved author inputs.

- For a draft request, stop after presenting it.
- For an update request, ask for approval after presenting the draft. After approval, update only the PR body with the available GitHub tool or `gh pr edit`, refetch it, and verify the five headings are present.
- If authentication or write access is unavailable, return the complete draft and the exact blocker without attempting another remote mutation.