GitHub Pull Request Workflow

Ship a PR a reviewer can land without follow-up clarifying questions. The aim is high signal in the title and body, evidence the change works, and clean replies when feedback comes in.

When to use

• You are about to open a PR for a change that is functionally complete.
• A reviewer left comments and you need to respond and push fixes.
• A PR has been open more than a day and needs to be brought back into shape (stale conflicts, missing description, missing verification).

When not to use

• The change is not yet functionally complete. Finish the work first; draft PRs that bounce on review are noise.
• The repository uses a non-GitHub forge. Adjust to that forge's conventions; do not force GitHub-isms.

Branch hygiene before opening

• Rebase or merge from the target base so the diff is current.
• Squash WIP commits into reviewable units. Prefer one commit per logical change; do not force one-commit-per-PR if the work is genuinely multi-step.
• Confirm tests, typecheck, and lint pass locally. Note any deliberate skips in the PR body.
• Remove debug prints, commented-out code, and TODO markers that are not tracked.

PR title

• Imperative mood, under 70 characters.
• Lead with the user-visible change, not the file touched. Allow CSV export from reports table beats Update reports.tsx.
• If the repo uses an issue prefix convention (PAP-1234:, [security]), follow it.
• No trailing period.

PR body

Use this structure:

## Summary
- 1, 3 bullets describing what changed and why.

## Implementation notes
- Anything non-obvious in the diff: trade-offs, dropped alternatives, gotchas.
- Migration or config implications.

## Verification
- The exact commands or steps you ran.
- Screenshots or short clips for UI changes (required if pixels moved).
- Edge cases you exercised by hand.

## Risk and rollback
- What breaks if this is reverted, and how to revert cleanly.