pr-description

name

pr-description

description

Use when the user wants to create a PR, draft a PR, open a PR, write or update a GitHub pull request description, summarize changes for reviewers, or asks for something like `write the PR description`, `draft the pull request description`, `help me open a PR`, or `turn these changes into a PR`. Produces a clean reviewer-facing PR description with a paragraph summary, file/component-grouped details, a checklist test plan, optional breaking changes, and a Codex model signature.

PR Description

Goal

Write PR descriptions that are easy for maintainers to review: explain why the change exists, group the implementation by files or components, state the test plan clearly, and avoid low-value boilerplate.

Trigger Examples

Use this skill for requests like:

• write the PR description
• create a PR
• draft a PR
• draft the pull request description
• summarize this for reviewers
• help me open a PR
• turn these changes into a PR description

Default Shape

Prefer this structure unless the user explicitly asks for a different project template:

PR Title

• Write a concise reviewer-facing title that describes the change.
• Do not include [codex], Codex, or other generated-by labels in the PR title.
• Prefer the repository's existing PR title style when it is clear from nearby history.

Summary

• Use prose paragraphs, not bullets.
• Keep the section to a few sentences.
• Explain why the change is being made and what problem it implements or fixes.
• Mention the high-level outcome, but leave concrete file/component changes for ## Details.
• Include issue references in this section when present, such as Fixes #123, after the summary paragraph.

Details

• Always use ## Details as the implementation section name.
• Use this section for concrete changes.
• Group bullets by file, workflow, or component.
• Add ### subheadings for each meaningful file/component group.
• Start bullets with strong verbs such as Add, Remove, Update, Align, or Refactor; bold action words only if the user asks for that style or the existing PR description already uses it.
• Mention file paths or workflow names in backticks when helpful, but do not force every bullet into a file-by-file format.
• Include rationale inline when it helps the reviewer understand why a detail matters.
• Avoid repeating every small diff line. Summarize related edits under the relevant file/component group.

Breaking Changes

• Include ## Breaking Changes only when the PR contains a genuine breaking change.
• Omit this section entirely when there are no breaking changes.
• Keep entries direct and actionable, including required user or maintainer action when known.

Test Plan

• Always include this section.
• Use the exact heading ## Test Plan.
• Use checklist format.
• Mention only the test plan and verification status. Do not include expected future CI results unless they are part of the intended test plan.
• Use - [x] for checks that were actually completed.
• Use - [ ] for planned or required checks that have not been completed.
• Mention exact commands, workflows, or reviewer-visible signals when known.
• If no local testing was run, say so plainly as a checklist item.

Signature

• Always end the PR description with a generated-by signature.
• Use the exact format Generated by Codex (<model>).
• Replace <model> with the current model display name when known, for example Generated by Codex (GPT-5).
• If the exact model is not known, use the most accurate model family available rather than inventing a precise version.

Style Rules

• Prefer plain technical language over marketing phrasing.
• Keep spacing clean: blank line after headings, then the paragraph or list.
• Avoid giant paragraphs and avoid one bullet per trivial edit.
• Do not restate obvious diff details line by line.
• Do not add ## Risks, ## Follow-ups, ## Review Notes, screenshots, rollout notes, migration notes, or other optional sections unless the user explicitly asks for them.
• Do not claim testing, review notes, or follow-up work that did not happen.

Example Shape

## Summary

This PR aligns the certification workflows with the execution environments they are meant to validate against. The change removes redundant sanity job configuration and makes the expected Python baseline explicit so the workflow behavior matches downstream usage.

Fixes #76

## Details

### `certification-reusable.yml`
- Remove the per-version sanity input so `ansible-test` can cover supported Python versions automatically.
- Hard-code the supported stable branches used by downstream execution environments.
- Add a pre-test step that writes `tests/config.yml` when the collection does not provide one.

### Calling workflows
- Update the reusable workflow callers to stop passing the removed input.
- Refresh comments and examples so the documented interface matches the workflow behavior.

## Test Plan

- [x] `zizmor` passes locally.
- [ ] CI passes for the PR workflow matrix.
- [ ] Sanity jobs run for each supported stable branch.

Generated by Codex (GPT-5)