Pull Requests

Pull Request Skill

When to Use This Skill

Use this skill when asked to:

• Create a pull request for the current branch.
• Update an existing PR branch or description.
• Rewrite a PR body.
• Follow up on CI or check failures for an existing PR.

References

Use the canonical docs for shared conventions and validation guidance:

• PR title and description conventions: .claude/docs/PR_STYLE_GUIDE.md
• Local validation commands and git hooks: AGENTS.md (Essential Commands and Git Hooks sections)

Body Formatting

GitHub renders the PR description as Markdown and soft-wraps paragraphs to the viewport. Do not hard-wrap prose at 72 or 80 columns. Insert manual line breaks only where Markdown needs them: between paragraphs, around headings, lists, tables, code blocks, and blockquotes.

The commit message body is not the PR body. Commit messages are typically hard-wrapped; PR bodies are not. When deriving the PR body from a commit message, unwrap each paragraph into a single line before passing it to gh pr create --body or --body-file.

Lifecycle Rules

1. Check for an existing PR before creating a new one:

   gh pr list --head "$(git branch --show-current)" --author @me --json number --jq '.[0].number // empty'
   

   If that returns a number, update that PR. If it returns empty output, create a new one.

2. Check you are not on main. If the current branch is main or master, create a feature branch before doing PR work.

3. Default to draft. Use gh pr create --draft unless the user explicitly asks for ready-for-review.

4. Keep description aligned with the full diff. Re-read the diff against the base branch before writing or updating the title and body. Describe the entire PR diff, not just the last commit.

5. Never auto-merge. Do not merge or mark ready for review unless the user explicitly asks.

6. Never push to main or master.

CI / Checks Follow-up

Always watch CI checks after pushing. Do not push and walk away.

After pushing:

• Monitor CI with gh pr checks <PR_NUMBER> --watch.
• Use gh pr view <PR_NUMBER> --json statusCheckRollup for programmatic check status.

If checks fail:

1. Find the failed run ID from the gh pr checks output.
2. Read the logs with gh run view <run-id> --log-failed.
3. Fix the problem locally.
4. Run make pre-commit.
5. Push the fix.

What Not to Do

• Do not reference or call helper scripts that do not exist in this repository.
• Do not auto-merge or mark ready for review without explicit user request.
• Do not push to origin/main or origin/master.
• Do not skip local validation before pushing.
• Do not fabricate or embellish PR descriptions.