create-pull-request

name	create-pull-request
description	Create or update a pull request for pg_trickle. Use when: opening a new PR, fixing a garbled PR description, updating an existing PR body, or preparing a PR after finishing a feature or fix. Handles the safe body-file workflow to avoid Unicode corruption.
argument-hint	Branch name or short description of the change (e.g. fix/scheduler-race)

Create Pull Request

Safe, Unicode-correct workflow for creating or updating GitHub pull requests in the pg_trickle repository. Never use shell heredocs or echo for PR bodies — they silently corrupt Unicode (math symbols, em-dashes, etc.) and can pick up stale content from a previous session.

When to Use

• Opening a new pull request after completing a fix, feature, or refactor
• Repairing a garbled PR description (gh pr edit)
• Updating the PR body after new commits

Prerequisites

• gh CLI authenticated (gh auth status)
• Working tree is clean or changes are committed
• Current branch is not main (never create a new branch unless the current branch is main — see AGENTS.md)

Procedure

Step 1 — Gather Context

Before writing the PR body, collect:

1. git log main..HEAD --oneline — commits included in the PR
2. git diff main --stat — files changed
3. Relevant plans or issues referenced by the branch name or commit messages
4. Check for an existing PR: gh pr list --head <branch>

Step 2 — Choose a Title

Format: <type>(<scope>): <short imperative summary> (conventional commits)

Type	When
feat	New user-visible capability
fix	Bug fix
perf	Performance improvement
refactor	Internal restructure, no behaviour change
test	Tests only
docs	Documentation only
chore	Build / CI / tooling

Keep the title under 72 characters.

Step 3 — Write the PR Description

Structure the body using this template:

## Summary

<!-- 2-4 sentences: what changed and why -->

## Changes

<!-- Bullet list of the most important changes -->
- …

## Testing

<!-- How the change was verified -->
- `just test-unit` — passes
- `just test-integration` — passes
- `just test-e2e` — passes (include relevant test names if targeted)

## Notes

<!-- Optional: migration steps, rollback plan, known limitations, follow-up issues -->

Step 4 — Write Description Using create_file Tool

CRITICAL: Use the create_file tool — never echo or a shell heredoc.

1. Delete any stale file at the target path first:

   rm -f /tmp/pr_<TICKETNAME>.md
   

2. Use create_file to write the body to /tmp/pr_<TICKETNAME>.md. The file is written in UTF-8 and read directly by gh --body-file, so Unicode characters (math symbols, em-dashes, arrows) are safe.

3. Verify the file is clean before using it:

   python3 -c "
   with open('/tmp/pr_<TICKETNAME>.md') as f:
       body = f.read()
   print('lines:', body.count(chr(10)))
   print('ok:', '####' not in body)
   print(body[:120])
   "
   

Step 5 — Create or Update the PR

New PR:

gh pr create \
  --title "<type>(<scope>): <summary>" \
  --body-file /tmp/pr_<TICKETNAME>.md \
  --base main

Fix garbled description on existing PR:

gh pr edit <number> --body-file /tmp/pr_<TICKETNAME>.md

Step 6 — Verify the Live PR Body

gh pr view <number> --json body --jq '.body' | head -20

Confirm the first heading and a Unicode character (if any) render correctly. If the body is garbled, re-run Step 3–5.

Branch Rules

• Never create a new git branch unless the current branch is main.
• Branch names follow <type>/<short-slug>, e.g. fix/scheduler-race, feat/window-function-diff.

Checklist Before Opening the PR

• just fmt && just lint passes with zero warnings
• Relevant test tier passes (just test-unit / just test-integration / just test-e2e)
• No unwrap() / panic!() in non-test code paths
• All unsafe blocks have // SAFETY: comments
• PR title follows conventional commit format
• PR body written via create_file tool (not heredoc / echo)
• Live PR body verified with gh pr view