Writing Pull Requests

Writing Pull Requests

Effective pull requests communicate the why behind changes, not the what. Code diffs already show what changed; the PR title and description convey motivation, impact, and context that accelerates review.

Core Principle: Repository Transformation

The PR title describes how the repository changes when the PR merges. The verb targets the repository capability, not the developer action.

The "Fill in the Blank" Technique

Complete this sentence with your title: "After this PR merges, the repository will _____."

The verb must make grammatical sense in this frame. Developer-action verbs fail the test:

Verb	"The repository will _____"	Works?
Parse MAC addresses	"The repository will parse MAC addresses"	Yes
Add rate limiting	"The repository will add rate limiting"	No
Handle nil emails	"The repository will handle nil emails"	Yes
Implement caching	"The repository will implement caching"	No

Developer-action verbs (add, implement, create, write, update, change) describe what the developer did. Repository-capability verbs (parse, handle, support, expose, enable, optimize, simplify, prevent, serialize, validate, extract) describe what the code does.

Quick Reference by Intent

Intent	Verbs
New capability	handle, parse, transform, validate, serialize, cache, pool
Improvement	optimize, simplify, consolidate, enhance
Fix	fix, correct, respect, prevent
Structural	extract, expose, define, introduce
Removal	remove, drop, deprecate
Configuration	configure, enable, disable
Documentation	explain, clarify, document

For comprehensive verb guidance and rationale, see examples/bad-pr-examples.md.

Title Structure

PR titles follow imperative mood, beginning with a verb:

Format: <Verb> <what the repository now does>

• Begin with an action verb in imperative form
• Describe the new capability or behavior
• Keep concise but descriptive
• Capitalize the first letter (it is a sentence)

Examples:

• Parse MAC addresses without separators
• Limit authentication attempts to prevent brute-force attacks
• Serialize connection pool cleanup to prevent leaks
• Extract authentication into dedicated service

Gathering Context

Before drafting a PR, gather context from multiple sources:

From Git

Analyze the working tree to understand the change scope:

1. Review the diff to understand what changed
2. Check commit history to see the progression of work
3. Note branch name conventions that may encode intent

From the Repository

Search for related context in the repository:

1. Check open issues that may relate to the changes
2. Review recently closed issues for ongoing efforts
3. Look at recent PRs touching similar areas

Use gh issue list and gh pr list to discover related work. Reference relevant issues in the PR description to connect the contribution to ongoing efforts.

From the Conversation

Draw context from the discussion that led to the changes:

1. Why was this change initiated?
2. What alternatives were considered?
3. What constraints shaped the solution?

When context is missing, ask proactively. The motivation behind a change is essential for a good PR.

Surfacing Hidden Context

PRs live in the solution-space: the author has made decisions and the changeset reflects those decisions. The description must surface the context that led to this solution.

What the Prose Must Capture

The diff shows what changed. The description must explain what the diff cannot convey:

• Expected outcome: What the change accomplishes (verifiable against the changeset)
• Intent behind the change: Why this change, why now
• Constraints that shaped the solution: Technical, organizational, or timeline limitations that drove this approach
• Designed exclusions: What this change explicitly does not address and why that's intentional
• Reevaluation triggers: Conditions under which this decision should be revisited
• Assumptions made: What must remain true for this solution to work
• Trade-offs accepted: What was sacrificed and why it was acceptable

Alternatives considered may be worth brief mention, but focus on constraints and exclusions over exhaustive comparison of rejected options.

Detecting Missing Context

Use intelligence to detect when essential context is missing. When gaps exist, ask targeted questions before drafting:

• "What constraint prevented the simpler solution?"
• "What is explicitly out of scope for this change, and why?"
• "Under what conditions should we revisit this approach?"
• "What should reviewers verify to confirm this works as intended?"

If the user cannot provide the information after being asked, insert actionable placeholders that specify exactly what information is missing and how to obtain it:

• [FILL: Ask the original author why X was chosen over Y]
• [FILL: Check git blame for commit message explaining this constraint]
• [FILL: Review linked issue for context on why this approach]

Placeholders must be specific enough that someone can act on them immediately.

Embedding Rationale in Code

When rationale is uncovered, check the changeset for appropriate places to embed it permanently. Respect existing project conventions - do not introduce new documentation patterns.

Preferred locations (in order of preference):

1. Code comments: Near the code the rationale affects - constraints, reevaluation triggers, non-obvious decisions
2. Doc strings: In existing function/method documentation - API contracts, assumptions, usage caveats
3. Existing documentation: If the project has architecture docs, design docs, or similar markdown files that already cover this area

Do not:

• Create ADR files if the project has no ADR convention
• Add niche sections to an otherwise generic README
• Introduce documentation patterns the project doesn't use

If no trivial code location exists, include the rationale in the PR description. The PR is the fallback, not the first choice - but it's better there than nowhere.

Repository Templates

Before drafting, check for repository-specific templates that encode team conventions.

Locating Templates

Search these paths (first match wins):

1. .github/pull_request_template.md
2. .github/PULL_REQUEST_TEMPLATE.md
3. docs/pull_request_template.md
4. pull_request_template.md (root)
5. .github/PULL_REQUEST_TEMPLATE/ (multiple templates)

Using Templates

When a template exists, evaluate fit:

• Good fit: Follow the template structure
• Partial fit: Use relevant sections, adapt others with judgment
• Poor fit: Draft freely but note why the template didn't apply

Templates are guides, not rigid forms.

Description Philosophy

PRs are solution-space documents. Issues define what needs solving (problem-space); PRs explain why this particular solution was chosen and what outcome it achieves.

The description explains why this solution exists and what outcome it delivers. The expected outcome must be verifiable: reviewers should be able to confirm the changeset achieves the stated intent.

The first paragraph immediately follows the title without a header. This opening carries the weight of explaining the change purpose.

When an issue is linked: The description can be brief since the issue provides problem-space context. Focus on the solution rationale: why this approach, what trade-offs were accepted.

When no issue exists: The description must compensate by providing both problem-space context (what prompted the change, who is affected) and solution-space rationale (why this approach over alternatives).

PR Scope

Keep PRs focused on a single logical change.

Signs of good scope:

• Reviewable in one sitting (under 400 lines typical)
• Single purpose evident from title
• All changes relate to stated intent

Signs of scope creep:

• "Also fixes..." or "While I was here..." in description
• Multiple unrelated file groups changed

When scope grows, split into stacked PRs or separate unrelated changes.

Proofs

Complex changes benefit from proof that they work as expected:

• Library code: Examples in code demonstrate capability; tests prove fixes
• Executables/backends: Manual verification in production-like environments

Link proofs using trailer format: Proof: org/repo#123 (comment)

Workflow

When creating a PR:

1. Gather context: Review diff, commits, branch name, and conversation
2. Search for related work: Check open/closed issues and recent PRs
3. Identify the capability: What does the repository do differently?
4. Draft title: Verb + capability (not developer action)
5. Write description: Focus on why, link related issues, include proof for complex changes
6. Review: Does the title describe repository transformation? Does the description explain motivation?

Reference Files

For detailed guidance, consult:

File	Contains
references/description-structure.md	Description format, prose flow, issue linking, post-merge patterns
examples/good-pr-examples.md	Effective PR examples with probe tags showing context discovery
examples/bad-pr-examples.md	Anti-patterns with detailed rationale for why they fail

About probe tags: Example files use <probe> tags to demonstrate targeted questions that surface essential context. Each probe shows what to ask ("What constraint prevented the simpler solution?", "What's the proof?") and the information it reveals. Use this pattern when gathering context before drafting.

What to Avoid

Rehashing commits in bullet lists The git log shows commits; the description explains intent the diff cannot convey. Describing file-by-file changes The diff shows which files changed. Describe the capability, not the file list. Starting with "This PR adds/implements/creates..." This describes developer action. Start with why this change matters or what outcome it achieves. Skipping context when no issue exists Without a linked issue, the description must provide problem-space context. "Fixes the bug" with no issue is meaningless. Using developer-action verbs in titles

Avoid	Why	Use Instead
add	Describes action of adding	handle, define, introduce
implement	Narrates development	handle, support, enable
update	Vague about what changed	optimize, fix, refactor (be specific)
change	Maximally vague	optimize, correct, simplify (be specific)
create	Focuses on creation not function	define, establish, introduce

These describe what the developer did, not what the repository now does. See examples/bad-pr-examples.md for comprehensive analysis.

Line Formatting for GitHub

GitHub's markdown renderer treats hard newlines within a paragraph as literal line breaks. When composing --body content for gh pr create, write each paragraph as a single continuous line with no mid-sentence wraps. Newlines should only appear:

• Between paragraphs (blank line)
• Before list items, headings, or code blocks
• Where markdown syntax requires them

This differs from git commit -m, where hard wraps are conventional because terminals render them directly.

Self-Review Checklist

Before presenting the PR:

Process:

• Read the diff as if seeing it for the first time
• Confirm CI passes (don't waste reviewer time on broken builds)
• Remove debug code and commented-out blocks
• Verify scope - no unrelated changes snuck in

Title:

• Begins with imperative verb describing repository capability
• Does NOT use developer-action verbs (add, implement, create, write)
• Describes how the repository changes, not what you did

Description:

• Opens with untitled paragraph explaining why
• Links related issues using full short syntax (org/repo#123)
• Includes proof for complex changes
• Uses prose flow, not bullet lists of changes
• If no linked issue, provides compensating context