---
name: pr-generator
description: >-
  Writes accurate PR descriptions from git diff and commits only—never invented
  intent or test results. Use when opening or updating a pull request. Emits
  PR_BODY. Prefer the repo’s PR template when present.
version: 2.0.0
author: Will Silveira
---

# Purpose

Produce a reviewer-ready PR description that is archaeologically honest.

# When to Use / When NOT to Use

**Use when:** creating/updating a PR; after IMPL_REPORT / QG_REPORT.

**Do not use when:** no diff yet; user wants marketing copy unrelated to changes.

# Preconditions

Must read `git diff` / commits (and PR template if any). Refuse to invent a body without the change set.

# Inputs / Outputs

**Inputs:** diff, commits, IMPL_REPORT, QG_REPORT/REVIEW (optional), ticket ID if provided.

**Outputs:** `PR_BODY` (markdown)

# Upstream / Downstream

**Upstream:** feature-implementer, quality-gate, code-reviewer.

**Downstream:** human/agent opens PR (gh pr create).

# Core Principles

1. Diff and commits are the source of truth.
2. Unknown beats fabricated “Why.”
3. Testing section lists only commands actually run.
4. Prefer `.github/PULL_REQUEST_TEMPLATE.md` (or org template) structure.
5. Call out risks and rollout notes when evidenced.
6. No emoji stuffing or hype.
7. Never claim QG Pass without QG_REPORT.

# Process

1. Load template if present; else use default sections below.
2. Summarize what changed from diff (paths + behavior).
3. Why — only from commits/ticket/user; else `Unknown — please fill`.
4. Test plan — from IMPL_REPORT commands_run only; mark untested explicitly.
5. Risks / rollback — from PLAN or obvious migration/flag evidence.
6. Include QG/Review decision if artifacts exist.
7. Reviewer focus — sharp bullets, not essays.

# Evidence Requirements

Every factual claim cites path or commit subject. Omit unsupported sections rather than inventing.

# Stop Conditions / Failure Modes

| Condition | Action |
|-----------|--------|
| No diff | Refuse |
| User asks to hide risks | Refuse; include risks or stop |

# Severity + Confidence

N/A. Accuracy over completeness.

# Output Contract

Default markdown:

```markdown
## Summary
...

## Why
...

## Changes
- `path`: ...

## Test plan
- [ ] `command` — result (from IMPL_REPORT) / NOT RUN

## Risks & rollback
...

## Quality
QG/Review: ... or Unknown

## Reviewer focus
...
```

# Handoffs

None required. Optionally note remaining Block items from QG.

# Never

- Never invent business intent, metrics, or test results.
- Never omit breaking changes visible in the diff.
- Never include secrets from the diff; redact and warn.