pr

name	pr
description	Create a good pull request

Creating a pull request

• NEVER say code was generated by Claude in a PR description

• Ensure the pull request title follows the Conventional Commits specification.

• Always create PRs as draft unless I explicitly say otherwise

• Always assign me (jmeridth) as the assignee when opening PRs - this helps me track work in progress and follow up

• Always check a PR's status (open/merged/closed) before pushing commits to it

• Format the pull request description using the PR contract headings:

  • Issue references (top, above What/Why) -- If the PR relates to or resolves an issue, put the reference line(s) at the very top of the body, above the ## What/Why heading. Use Relates to #<n> for a non-resolving link, and Fixes #<n> / Closes #<n> only when merging the PR should actually close that issue. One reference per line.
  • ## What/Why -- Intent in 1-2 sentences. Combine the what and why into a single concise statement.
  • ## Proof it works -- Tests passed, manual verification steps, screenshots, or logs. Do not list linting results here -- linting is a given. Focus on meaningful tests: unit tests, integration tests, manual verification, etc.
  • ## Risk + AI role -- Risk tier (low/medium/high) and which parts were AI-generated (e.g., "high -- touches payments"). If no AI was involved, say so.
  • ## Review focus -- 1-2 specific areas where human reviewer input matters most (e.g., architecture, security, edge cases).

• No closing keywords in prose: Never write GitHub closing keywords (fix/fixes/fixed, close/closes/closed, resolve/resolves/resolved, with or without a colon) directly before an issue number inside a paragraph or heading. GitHub treats fixes #123 anywhere in the body as a close-on-merge link, so prose like "the failure this fixes: #123" will silently close #123 when the PR merges. Keep all such keywords confined to the dedicated reference lines at the top. When only mentioning an issue in prose, use a neutral phrasing such as "see #123" or "example: #123".

• PR descriptions should be kept up to date with the actual changes -- verify before finalizing

• When reviewing PRs, focus on critical issues (bugs, security, logic errors) not style nitpicks

• Verify before flagging: When reviewing code, always check source material (config files, upstream docs, official examples) before recommending changes. Do not flag something as a bug or missing requirement based on assumptions alone.

• Suggest code changes: When posting PR comments that request specific code changes, use GitHub's suggestion blocks (````suggestion`) so the author can apply the fix directly.

• Additive tone in reviews: Frame feedback as additive rather than corrective. Say "we've also got" instead of "but we've got". Use "I believe" to soften assertions about behavior you haven't directly verified (e.g., "I believe it passes because" not "It only passes because").

• Tone down superlatives: Use "a good move" over "the right move" - softer assertions feel less prescriptive.

• One point per comment: Keep review comments focused on a single actionable suggestion. Don't dilute the feedback with secondary praise or unrelated observations.

• Be precise with references: When referring to something (code, suggestions, links), make it obvious what "this" refers to - e.g., "this suggestion above" not just "this".

• Always confirm before approving PRs unless explicitly told to approve. Asking to see the approval message is not the same as giving the go-ahead.

• Check existing review feedback before commenting: When reviewing a PR, always read through existing review comments and threads first. Do not post a concern that has already been raised by another reviewer - it creates noise and makes it harder for the author to track actionable feedback.

• Always use the repo's PR template: Before opening a PR, check for a pull request template (e.g., .github/pull_request_template.md or .github/PULL_REQUEST_TEMPLATE.md) in the target repository and use it as the structure for the PR description. Do not write a PR body from scratch when a template exists.

• Mark Ready When Ready label: When creating a draft PR, check if both of these conditions are true: (1) the repository has a label named "Mark Ready When Ready" (gh label list --search "Mark Ready When Ready"), and (2) a GitHub Actions workflow in .github/workflows/ references the kenyonj/mark-ready-when-ready action. If both conditions are met, add the "Mark Ready When Ready" label to the draft PR. If either condition is not met, notify me that the label was not applied and which condition(s) failed.

• Public vs private repo: Before writing the PR description, check whether the target repository is public or private (gh repo view <owner>/<repo> --json visibility -q .visibility). If the repo is public, keep the PR description generic and do not include any proprietary or internal information. Specifically:

  • Do not link to internal trackers (Linear, internal Jira, internal Confluence)
  • Do not reference internal project names, environments, customer names, infra hostnames, internal IPs, internal SA emails, or internal repo names
  • Do not reference companion PRs in private repositories
  • Phrase the "Why" in generic terms (e.g., "reach addresses on a private network" instead of "reach the PSC endpoint at 10.10.0.108")
  • Avoid mentioning specific GCP/AWS/Azure resources, project IDs, or internal team names
  • If the change was driven by an internal incident or initiative, describe the technical problem without naming it
  • Generic open-source framing is fine; the technical content of the change should still be accurate and complete
  • If unsure whether something is sensitive, omit it or ask before posting