Create Pull Request

Create a GitHub pull request using gh pr create, populating every section of the project's PR template at .github/pull_request_template.md.

Gathering Context

Before writing the PR body, collect information about what changed on this branch. Run these commands to understand the full scope of the PR — not just the latest commit, but ALL commits since the branch diverged from the base.

# Determine base branch (default: main, or use $ARGUMENTS if provided)
BASE="${ARGUMENTS:-main}"

# All commits on this branch
git log "$BASE"..HEAD --oneline

# Files changed with stats
git diff "$BASE"..HEAD --stat

# Full diff for reading the actual changes
git diff "$BASE"..HEAD

# Recent merged PRs for style reference
gh pr list --state merged --limit 5 --json title,body

Read the full diff carefully. You need to understand every change to write an accurate PR description.

Filling In the Template

What changed

Write a concise summary of what the PR does at a high level — the kind of thing a reviewer reads to orient themselves before looking at code. Follow with a breakdown by file or area, using bold filenames or directory names as headers. Focus on what changed and why, not line-by-line narration.

Decisions reviewers may ask about (optional)

Add this section, right after "What changed", only when the PR makes choices a reviewer — human or agent — could reasonably question. Skip it for straightforward PRs; an empty or padded section is worse than none.

Good candidates:

An approach chosen over a plausible alternative (and why the alternative lost).
Something deliberately left alone, or deliberately not tested, that a reviewer might flag as a gap.
A non-obvious technical constraint that explains odd-looking code (e.g. a migration quirk).
A deviation from a convention or from what the ticket literally says.
A rollout or deploy-ordering risk, or an irreversible step.
Out-of-scope follow-ups you noticed but did not do.

Format: one bullet per decision, the likely question in bold, then the answer with the reason. Keep each to one or two sentences, and don't restate the diff — every bullet should be something that could draw a review comment. Check each claim against the code before writing it down; a wrong rationale in the PR is worse than none.

This is a public repo: don't name real users, user IDs, or production infrastructure resources in this section.

Issue

Extract the ticket number from the branch name (the project convention is OPS-NNNN/description). Format it as a link:

https://github.com/HHS/OPRE-OPS/issues/<number> (or reference the Jira/ticket tracker the team uses)

If the branch name doesn't contain a ticket number, ask the user.

How to test

Write concrete, actionable steps a reviewer can follow to verify the change works. Include specific commands (with paths) for running relevant tests. If the change affects the UI, include steps for manual verification too. Think about what a reviewer unfamiliar with this part of the codebase would need.

A11y impact

Check whether the diff touches any frontend files (anything under frontend/src/). If it does, leave the checkboxes unchecked for the user to decide. If the PR is backend-only or has no UI changes, check the "No accessibility-impacting changes" box:

- [x] No accessibility-impacting changes in this PR

Definition of Done Checklist

Analyze the diff to determine which checklist items are relevant:

If the PR includes test changes: check "Automated unit tests updated and passed" and/or "Automated integration tests updated and passed"
If there are refactoring changes: check "OESA: Code refactored for clarity"
Leave items unchecked when you can't verify them (coverage numbers, load tests, security tests, etc.) — the author will confirm these
For backend-only PRs, "Form validations updated" is typically not applicable — leave unchecked

Screenshots

If the PR is backend-only or has no visual changes, write "N/A — backend changes only" or similar. If there are frontend changes, note that screenshots should be added and leave a placeholder.

Links

Include links to related PRs, documentation, or design docs if they appear in commit messages or are otherwise evident. Otherwise write "N/A".

Creating the PR

Extract a short, descriptive PR title (under 70 characters) from the changes. Use conventional commit style if it fits naturally (e.g., "feat(procurement): add tracker creation during spreadsheet ingest").

Before creating the PR:

Check if the branch has been pushed to the remote. If not, push it with git push -u origin HEAD.
Confirm with the user: show them the title and a summary of what the PR body will contain. Ask "Ready to create?" before running gh pr create.

Use a HEREDOC for the body to preserve formatting. If you are including the optional decisions section, add ## Decisions reviewers may ask about between What changed and Issue:

gh pr create --title "the pr title" --body "$(cat <<'EOF'
## What changed
...

## Issue
...

## How to test
...

## A11y impact
...

## Screenshots
...

## Definition of Done Checklist
...

## Links
...
EOF
)"

After creating the PR, display the PR URL to the user.

create-pr