# Pull Requests

> Guide for creating, updating, and following up on pull requests in the Coder repository. Use when asked to open a PR, update a PR, rewrite a PR description, or follow up on CI/check failures.

- Skill: `coder/pull-requests` (Agent Skill)
- Install (CLI): `npx skillmds@latest add coder/pull-requests`
- Raw SKILL.md: https://api.skillmd.com/api/skills/coder/pull-requests/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: coder (https://skillmd.com/u/coder)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/coder/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:

   ```bash
   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.