Write a pull request description
Writes a pull request description that tells reviewers why the change exists, what to look at first, how to test it and what could break. Use when opening a PR.
A PR description is for the reviewer, who has less context than the author and limited time. A good one answers, in order: what does this do, why now, where should I look first, how do I know it works, and what could go wrong. It is not a changelog of every file and not a sales pitch. Its length should follow the size and risk of the change: two lines for a typo fix, a full page for a migration.
Write the description for Only if [CHANGES] is given: . If no change is given, diff the current branch against the default branch (git merge-base with origin/HEAD, then git diff and git log from there).
Only if [WHY] is given:
Reason given by the author:
Only if [TEMPLATE] is given:
Use the headings of this template instead of the default ones, and fill every section it has:
- Read every commit message and the full diff before writing. Check the repo for a PR template (
.github/pull_request_template.md,.github/PULL_REQUEST_TEMPLATE/,docs/) and use it if one exists. - State the purpose in one or two sentences a reviewer could repeat.
- Group the changes by intent, not by file. Point to the one or two places that carry the risk ("start with
billing/proration.ts; the rest is wiring"). - Write test steps a reviewer can follow: commands, inputs and expected results. Include only tests and checks you can see in the diff or the input.
- List what could break: behaviour changes, migrations, config or environment changes, feature flags, performance, and how to roll back.
- Never claim that tests pass, that something was tested manually, or that metrics improved unless the input says so. Write
TODO(author): ...for anything only the author can confirm. - Link issues only when the id appears in the branch name, commits or input. Never invent one.
- Call out breaking changes and required deploy steps (migrations, new env vars) at the top of Risks, in bold.
- No filler ("This PR aims to..."), no restating the title, no emoji unless the template uses them.
- Do not create or edit the PR yourself; output the text.
First line: a proposed PR title in the repo's commit style, under 72 characters. Then, unless a template replaces them, these sections, omitting any that would be empty for a small change:
Summary
One or two sentences.
Why
The problem or ticket, with the link if known.
Changes
Bullets grouped by intent. Name the files to review first.
How to test
Numbered steps with expected results.
Risks
Breaking changes, migrations, rollout and rollback, or "Low: ..." with the reason.
Every required value is filled in. Copy gives the finished prompt.
details
- kind
- Prompt: a task you run by name to get one finished thing back
- domain
- Software engineering
- category
- Git and version control
- level
- Beginner
- made for
- Software engineer, Tech lead / staff engineer
- needs
- repo-read, git
- risk
- read-only
- version
- v1.0.0 · experimental
- reviewed
- 2026-10-02
- works in
- Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md
use in
npx @hermes-hq/hodios install write-pr-description --target claude-codenpx skills add hermes-hq/hodios-dist --skill write-pr-description -a claude-codeclaude plugin marketplace add hermes-hq/hodios-distclaude plugin install hodios-software-engineering@hodiosThe plugin brings every entry in this domain at once.
pairs well with
All of Git and version controlWrite a commit message
Writes a commit message that states what changed and why, in the repo's own convention, and flags staged changes that should be split. Use before committing.
write-commit-messageReview a pull request
Reviews a pull request diff for correctness bugs, risky changes and missing tests, and returns ranked findings. Use before merging a PR, branch or diff.
review-pull-requestRecover lost Git work
Recovers commits, branches, stashes and staged files lost to a reset, rebase or dropped stash, using reflog and fsck after a backup, explaining each command. Use right after a git mistake.
recover-lost-git-workResolve a merge conflict
Resolves merge, rebase or cherry-pick conflicts by reading both sides and their common base, keeps the intent of each, and asks when the intents contradict. Use when git stops on a conflict.
resolve-merge-conflictChoose a branching strategy
Recommends a branching and release strategy such as trunk-based, GitHub flow or release branches for a team's size, cadence and environments, with rules, protections and migration steps.
choose-branching-strategyClean up a branch's commit history
Plans an interactive rebase that turns a messy branch into logical, reviewable commits, with a backup, the exact todo list and a check that the code is unchanged. Use before merging a WIP branch.
clean-up-commit-history