Creating a pull request

Creating a Pull Request

Overview

A PR is read by two audiences at once: someone who needs to know what changed and why it matters without reading code, and a developer who needs to know what the code does and why it was written that way. Write for both, every time.

Core principle: Plain-language meaning first, technical detail second — never skip the first to get to the second. This is the dmi-superpowers:say discipline applied to a PR.

Announce at start: "I'm using the creating-a-pull-request skill to write this PR."

The Process

Step 1: Detect a repo PR template

ls .github/PULL_REQUEST_TEMPLATE.md .github/pull_request_template.md \
   .github/PULL_REQUEST_TEMPLATE/ docs/PULL_REQUEST_TEMPLATE.md 2>/dev/null

• Template found: fill out the template's sections. Still write the prose in the house style (Step 3) — if the template has no slot for a plain-language summary or a developer TLDR, add them at the top of the body before the template's sections.
• No template: use the default body in Step 3.

Step 2: Write the title

Plain-language and concise. Name the outcome a non-developer cares about, never the mechanism.

Self-check before you commit the title: does it name a mechanism — a library, pattern, data structure, function, or endpoint (e.g. "pagination", "circuit breaker", "cursor", "/customers")? If so, rewrite it as the outcome that mechanism produces.

• ✅ Speed up the admin dashboard by loading customers in pages — names the outcome
• ❌ Add cursor-based pagination to the /customers endpoint — names the mechanism
• ✅ Stop losing background updates when the server is briefly busy
• ❌ Add retry-with-backoff and circuit breaker to sync_worker

Step 3: Write the body

The body is a contract with these parts, in this order:

1. Summary (always) — for a non-developer. Written in non-technical language that a non-developer can understand. It should contain two parts, in order: the problem — what wasn't working, was missing, or was slow, stated so a non-engineer feels why it mattered — then the solution — what the solution is and how the PR implements the solution.

2. TLDR for developers (always) — for a developer. What code changed (files, functions, key mechanisms) and why it was written this way — the reasoning behind the approach, not just a restatement of the diff.

3. Evidence (when meaningful and helpful) — proof it works. Before/after UI screenshots, or before/after server log excerpts, that demonstrate the bug is fixed or the feature works. Omit only when there is genuinely nothing visual or observable to show; say so if you omit it.

Step 4: Create the PR

git push -u origin <branch>
gh pr create --title "<plain-language title>" --body "<body from Step 3>"

Example (no-template body)

Summary

Problem: When the server we sync with restarts, it briefly turns requests away. Our app took that first "not now" as final and gave up, so updates were silently lost during every restart. Solution: The app now waits a moment and tries again a few times, and if the server stays down it backs off for half a minute instead of piling on. Updates survive a restart; nothing is dropped.

TLDR for developers

• sync_worker.py: wrapped the upstream call in retry-with-exponential-backoff (3 attempts, jittered). Jitter avoids a thundering-herd retry spike when many workers recover at once.
• Added a circuit breaker: opens after 5 consecutive failures and pauses syncing for 30s, so we don't hammer an upstream that is genuinely down rather than blipping.
• Tests cover the backoff schedule and the breaker's closed→open→reset transitions.

Evidence

Before (logs): event 4f2 dropped: upstream 503 ×17 during the 12:04 deploy. After (logs): event 4f2 retry 2 succeeded — 0 dropped across the same deploy window.

Quick Reference

Part	Audience	Required?	Must contain
Title	Non-developer	Always	Plain-language outcome, concise
Summary	Non-developer	Always	Plain language: the problem, then the solution
TLDR for developers	Developer	Always	What changed + why this way
Evidence	Both	When meaningful	Before/after screenshots or logs

Common Mistakes

• Jargon title ("Add circuit breaker to sync_worker") — name the outcome a non-developer cares about instead.
• Opening with the technical summary — the first thing readers see must be the plain-language Summary.
• Solution without a problem — a Summary that only says what changed leaves a non-engineer with no idea why it mattered. State the problem first, then the solution.
• Reaching for an analogy — a plain statement of the problem and the solution is the goal, not a metaphor. Skip analogies.
• Merging lay and dev explanations into one block — keep Summary and TLDR as separate sections.
• Skipping evidence when it exists — if there's a reproducible before/after, show it.
• Template overrides the house style — a repo template tells you which sections to fill, not how to write them. Plain-language Summary + developer TLDR still apply.