---

name: using-pr description: Guide for creating pull requests that get reviewed fast — conventional titles, descriptions generated from branch commits, size discipline, test plans, and gh CLI workflow. Bridges using-commit (input) and using-review-comments (output). Trigger: "create a PR", "open a pull request", "write the PR description", "prepare this branch for review", "crear un PR", "abrir pull request", "descripción del PR". license: MIT metadata: author: jrodrigopuca version: "1.0"

Pull Request Guide

Write PRs that respect the reviewer's time — because review latency, not code speed, is what usually gates delivery.

Overview

A PR is an argument addressed to a reviewer: this change is correct, here's how to verify it, and here's what to look at first. If the branch has good conventional commits (using-commit), most of the description already exists — this skill assembles and edits it.

Instructions

1. Title — Conventional, Because It Becomes History

With squash-merge (the common case), the PR title becomes the commit subject on main — so it follows the exact using-commit rules:

feat(payments): add refund endpoint          ✅
fix(auth)!: migrate sessions to JWT          ✅ (breaking marked)
Final changes + review fixes                  ❌ (this lands in main's history!)

2. Description — Generated From the Branch, Then Edited

Extract the raw material:

git log main..HEAD --oneline --no-merges     # the story so far
git diff main...HEAD --stat                  # blast radius

Assemble into the template (full version in references/template.md):

## Summary
{2-4 lines: WHY this change exists — the problem, not the diff.}

## Changes
{Grouped from the commits — not one bullet per commit, one per logical change.}

## Test plan
{How this was verified: commands run, cases covered, what reviewers
can run themselves. "CI passes" alone is not a test plan.}

## Breaking changes / migrations
{Only if real: what breaks, migration steps. Omit the section otherwise.}

Closes #123
JIRA: PROJ-456

Editing rules (same discipline as create-changelog):

• Summary answers "why" — the diff already shows the what
• Merge fixup noise: 12 commits ≠ 12 bullets
• Guide the review: "start with RefundService; the rest is plumbing" is the single highest-value sentence you can write
• Screenshots/recordings for anything visual — before/after

3. Size Discipline

Review quality collapses with size: a 2,000-line PR gets a rubber stamp ("LGTM"), not a review.

• Target < ~400 changed lines of reviewable code (generated files, lockfiles, and snapshots don't count — say so in the description)
• Bigger than that? Split it: by commit sequence (the using-commit atomic series maps 1:1 to stacked PRs), refactor-first-then-feature, or feature-flag the increments
• If it genuinely can't be split (a migration touching everything), warn the reviewer and provide a reading order

4. Self-Review First

Before requesting review, read your own diff in the PR UI — different context reveals what the editor hid:

• Leftover debug code, commented blocks, accidental file changes
• Missing tests for the failure paths
• The place where YOU hesitate is where the reviewer will too — annotate it preemptively with a comment (note: … per using-review-comments)

5. Draft vs Ready

• Draft = CI can run, feedback on direction welcome, not review-ready
• Ready = you'd merge it as-is; every reviewer minute now costs someone's focus
• Don't mark ready to "get in the queue" — that trains reviewers to ignore the queue

6. gh CLI Workflow

gh pr create --title "feat(payments): add refund endpoint" \
             --body-file pr-body.md --base main [--draft]
gh pr view --web                     # verify rendering
gh pr ready                          # draft → ready
gh pr merge --squash                 # title becomes the commit

More commands (reviewers, labels, checks, stacked PRs): references/template.md.

Suite Handoffs

• Upstream using-commit: atomic conventional commits make the description assemble itself — garbage commits in, garbage description out
• Downstream using-review-comments: the review this PR receives should use conventional comments; respond per its author-side rules
• create-changelog: the squashed title is exactly what the changelog generator will consume — one more reason it must be conventional

Anti-Patterns

• ❌ The mystery PR — no description, "see commits". The reviewer reconstructs your reasoning at 10x the cost you saved
• ❌ The kitchen sink — feature + drive-by refactors + dep bumps in one PR; each dilutes review of the others
• ❌ "Fixed review comments" as a commit that will be squashed anyway — fine locally, but never as the PR title
• ❌ Re-requesting review without answering the comments — resolve or respond first (using-review-comments, author side)

Resources

• references/template.md — full PR template, gh commands, review-readiness checklist
• gh pr docs · Google's small CLs guidance
• Siblings: using-commit · using-review-comments · create-changelog