Skip to content
Skills Library
Programming · Writing

write-pull-requests

/write-pull-requests

Use when opening or updating a pull request — produces a bug-fix or feature description reviewers from junior to CTO can follow end to end.

Licence
MIT
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when opening or updating a pull request — produces a bug-fix or feature description reviewers from junior to CTO can follow end to end.

Original author description

Use when opening or updating a pull request — produces a bug-fix or feature description reviewers from junior to CTO can follow end to end.

How it works

  1. 1. Audit — what does the branch ship, and does a PR exist?
  2. 2. Decide the shape
  3. 3. Fill the sections — exactly these, in this order
  4. 4. Self-check against the audience contract
  5. 5. Create or update
  6. 6. Verify
  7. References
Original SKILL.md headings · 122 lines, 887 words
SKILL.md preview
---
name: write-pull-requests
description: Use when opening or updating a pull request — produces a bug-fix or feature description reviewers from junior to CTO can follow end to end.
---

# Write Pull Requests

The description is the cheapest review tool the author controls: it decides whether the
reviewer follows the change or reverse-engineers it. Two fixed shapes, filled from the
diff and from output that actually scrolled by — never from memory of what you meant to
build.

## 1. Audit — what does the branch ship, and does a PR exist?

```bash
BASE=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)   # or: git symbolic-ref --short refs/remotes/origin/HEAD
git log "origin/$BASE"..HEAD --oneline
git diff "origin/$BASE"...HEAD --stat  # or: git show <sha>, for a PR shipping one existing commit
ls .github/PULL_REQUEST_TEMPLATE.md .github/pull_request_template.md \
   .github/PULL_REQUEST_TEMPLATE/ 2>/dev/null
gh pr view --json number,title,body 2>/dev/null
```

Change nothing yet. Three findings decide the rest:

- **The diff is the source of truth.** Describe what the branch ships — including the
  commit you forgot — not what you remember working on.
- **A repo template wins.** If `.github/` defines a PR template, fill *its* sections in
  *its* order, and carry this skill's discipline into whatever slot asks for testing or
  verification. The shapes below apply only when the repo has none.
- **An existing PR means update, not create.** Step 5 edits it in place; never open a
  duplicate. If the body already matches what the branch now ships, exit — nothing to do.

## 2. Decide the shape

One question: does the branch **restore intended behavior** (bug fix) or **change or
extend it** (feature)? Mixed branches lead with the dominant shape and carry the
remainder under Notes. Edge cases (refactors, mixed branches): `./pr-patterns.md`.

## 3. Fill the sections — exactly these, in this order

**Bug fix:**

1. **Problem** — the user-visible symptom, in plain words: what broke, who hit it.
2. **Root cause** — the mechanism actually found, not the first suspicion.
3. **Fix** — what changed, and why this way.
4. **Tests** — coverage added or extended; name the test that now catches the bug.
5. **Verification** — the commands run and their observed output. Evidence, never
   claims (`./pr-patterns.md`).
6. **Notes** — tradeoffs, follow-ups, review hints.

**Feature:**

1. **Summary** — two or three sentences a CTO reads first: what ships, why it matters.
2. **Problem** — the need, in plain words: what couldn't be done before.
3. **Solution** — the approach chosen; the rejected alternative in one line when the
   diff or commits record one — "Rejected: none recorded" is honest too.
4. **Implementation** — the shape of the change in the code: key files, seams touched.
5. **Tests** — coverage added or extended.
6. **Verification** — commands run and observed output.
7. **Notes** — tradeoffs, follow-ups, review hints.

Non-trivial PRs close with the merge checklist, posted unticked (skip it for one-line
fixes and when the repo template has its own):

```markdown
## Before merge
- [ ] Manual review
- [ ] Smoke tested
- [ ] Pipeline green
```

A box is ticked by whoever verified it — the reviewer for the manual read, the author or
CI for the rest. A pre-ticked box with nothing behind it is decoration, not evidence.

No invented headings, no omissions: content that fits no section goes under Notes or
stays out. For Verification, run the commands *now* and paste the lines that prove the
point; anything not run is declared — "Not run: needs staging" — an honest gap beats a
fabricated pass. Write the assembled body to a temp file (`mktemp`, keep its path in `BODY`); step 5 posts that file. Any
attribution trailer your tooling requires goes last, after the checklist; it is not a
section.

## 4. Self-check against the audience contract

Read the draft as the three readers of `../_shared/audience.md`:

- **Junior** — can they follow Problem → Fix (or Solution) without tribal knowledge?
  Every internal codename expanded on first use?
- **Senior** — does every claim have its evidence under Tests or Verification? A bare
  claim gets its proof moved in, or gets softened to what the evidence supports.
- **CTO** — do the headings and first lines alone carry outcome and risk?

Plain prose throughout. A sentence that reads like a release announcement gets rewritten
as a fact.

## 5. Create or update

Show the title and body for approval first — pushing and opening a PR publish the draft.

```bash
git push -u origin HEAD               # if not yet pushed
gh pr create --title "<subject>" --body-file "$BODY"
# or, when step 1 found an existing PR:
gh pr edit <number> --body-file "$BODY"
```

The title carries the branch's dominant commit subject; a subject past ~72 characters
is compressed — keep the `type(scope):` and the one concern
(`../write-commit-messages/SKILL.md`). Editing the existing body in place is this skill's idempotency: a re-run regenerates the
description from the current diff and lands on the same PR.

## 6. Verify

```bash
gh pr view
```

Expected: one PR for the branch; six (bug fix) or seven (feature) sections in the fixed
order, closed by the Before-merge checklist (non-trivial PRs) — or the repo template's own; every
Verification entry is a command plus its observed output, not an adjective.

## References
- ./pr-patterns.md — why evidence beats assertion, Problem vs Summary, the shape decision, a filled example, when to deviate.
- ../_shared/audience.md — the junior-to-CTO contract step 4 checks against.
- ../write-commit-messages/SKILL.md — the commit subjects the title and Summary draw from.
Files in this package (2)
  • SKILL.md 6 KB
  • pr-patterns.md 9 KB

Versions

The database has no other skills named write-pull-requests.

Database snapshot: 13.11.2026 · package version b86c8389d332 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90pr
    Use when writing or updating a pull request description, or before running `gh pr create`.
  • 100write-commit-messages
    Use when committing work or writing a commit message — produces a subject and body any developer from junior to CTO can read and act on.
  • 100pr-description
    Write a pull request description from the actual diff and the work item: why (problem and link), what changed, how it was tested with evidence, risks and rollback, what reviewers should look at first, and checklist items (migrations, config, feature flags, docs). Use when…
  • 96updating-pr-title-and-description
    Pull Request作成・更新時に使用。タイトルと説明文を自動生成・更新する。
  • 90gh-pr-description
    Drafts and reviews GitHub pull request descriptions for the eve repository. Use when opening, updating, or reviewing a PR, or when summarizing a branch for reviewers.
  • 100pr-description
    Use when writing or updating a pull request or merge request description for the current branch, for GitHub, GitLab, or Bitbucket.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.