PR Description Writer
Use this skill to produce PR descriptions that help reviewers understand what
changed and why. The description must explain concrete behavior and code
changes, not just list touched files, dependencies, generated artifacts, or
snapshot churn.
Workflow
- Inspect the available context:
- current diff, branch range, or PR diff
- commit list and commit messages
- existing PR body, issue, bug report, spec, design doc, or upstream source
- validation commands and residual risks
- Group changes by reviewer-relevant behavior or subsystem. Prefer categories
such as API behavior, provider conversion, stream/wire format, UI behavior,
persistence, docs/examples, tests/fixtures, or tooling.
- For each group, explain:
- what changed in code or behavior
- why the change was needed
- what evidence or reference supports it
- Reference upstream/source context when it materially explains the change:
upstream implementation, tests, release notes, specs, issues, review
comments, or conformance fixtures. Mention references next to the relevant
change, not only in a generic footer.
- Separate generated or mechanical updates from semantic changes. Generated
snapshots, lockfiles, schema output, or formatter churn should support the
behavioral explanation, not replace it.
- Include validation commands actually run. Do not imply checks passed if they
did not run.
- Include residual risk, accepted deviations, skipped tests, or follow-up work
when relevant.
- Keep the result concise enough for reviewers to scan. Prefer precise bullets
over broad prose.
Structure
Use this structure by default and omit sections that do not apply:
## Summary
- One to four bullets describing the outcome in reviewer-facing terms.
- Include the main code/behavior changes, not only version or dependency bumps.
## Code Changes
- Area: concrete change, reason, and reference when useful.
- Area: concrete change, reason, and reference when useful.
## Tests And Fixtures
- What tests, fixtures, snapshots, or generated artifacts changed and what they
prove.
## Validation
- `command`
- `command`
## Residual Risk
- Accepted gaps, intentional deviations, skipped fixtures/tests, blockers, or
follow-ups.
For small PRs, merge Code Changes and Tests And Fixtures into Summary.
For release, parity, migration, or generated-heavy PRs, keep the sections
separate so reviewers can distinguish behavior from generated output.
Quality Bar
- Avoid vague bullets like "updates provider code" or "regenerates snapshots"
unless followed by the behavior that changed.
- Avoid file-by-file summaries unless each file maps cleanly to a reviewer
concern.
- Do not describe unrelated opportunities discovered during review as PR scope.
- Do not overstate certainty. Use "documents residual risk" or "leaves follow-up"
when behavior remains intentionally incomplete.
- Preserve conventional PR titles and repository-specific PR norms.
1---2name: pr-description-writer3description: Write or rewrite pull request descriptions from a branch diff, commit range, existing PR, issue, upstream reference, specification, bug report, or review context. Use when an agent needs to create, update, or improve a PR body so it explains concrete code and behavior changes, why they were made, validation performed, and remaining risk.4---56# PR Description Writer78Use this skill to produce PR descriptions that help reviewers understand what9changed and why. The description must explain concrete behavior and code10changes, not just list touched files, dependencies, generated artifacts, or11snapshot churn.1213## Workflow14151. Inspect the available context:16 - current diff, branch range, or PR diff17 - commit list and commit messages18 - existing PR body, issue, bug report, spec, design doc, or upstream source19 - validation commands and residual risks202. Group changes by reviewer-relevant behavior or subsystem. Prefer categories21 such as API behavior, provider conversion, stream/wire format, UI behavior,22 persistence, docs/examples, tests/fixtures, or tooling.233. For each group, explain:24 - what changed in code or behavior25 - why the change was needed26 - what evidence or reference supports it274. Reference upstream/source context when it materially explains the change:28 upstream implementation, tests, release notes, specs, issues, review29 comments, or conformance fixtures. Mention references next to the relevant30 change, not only in a generic footer.315. Separate generated or mechanical updates from semantic changes. Generated32 snapshots, lockfiles, schema output, or formatter churn should support the33 behavioral explanation, not replace it.346. Include validation commands actually run. Do not imply checks passed if they35 did not run.367. Include residual risk, accepted deviations, skipped tests, or follow-up work37 when relevant.388. Keep the result concise enough for reviewers to scan. Prefer precise bullets39 over broad prose.4041## Structure4243Use this structure by default and omit sections that do not apply:4445```markdown46## Summary4748- One to four bullets describing the outcome in reviewer-facing terms.49- Include the main code/behavior changes, not only version or dependency bumps.5051## Code Changes5253- Area: concrete change, reason, and reference when useful.54- Area: concrete change, reason, and reference when useful.5556## Tests And Fixtures5758- What tests, fixtures, snapshots, or generated artifacts changed and what they59 prove.6061## Validation6263- `command`64- `command`6566## Residual Risk6768- Accepted gaps, intentional deviations, skipped fixtures/tests, blockers, or69 follow-ups.70```7172For small PRs, merge `Code Changes` and `Tests And Fixtures` into `Summary`.73For release, parity, migration, or generated-heavy PRs, keep the sections74separate so reviewers can distinguish behavior from generated output.7576## Quality Bar7778- Avoid vague bullets like "updates provider code" or "regenerates snapshots"79 unless followed by the behavior that changed.80- Avoid file-by-file summaries unless each file maps cleanly to a reviewer81 concern.82- Do not describe unrelated opportunities discovered during review as PR scope.83- Do not overstate certainty. Use "documents residual risk" or "leaves follow-up"84 when behavior remains intentionally incomplete.85- Preserve conventional PR titles and repository-specific PR norms.
grafana