pull-request-management

Pull Request Management & Creation Skill

This skill guides AI agents and contributors on how to create, format, and manage Pull Requests (PRs) across repositories.

1. Core Pull Request Rules

IMPORTANT

LOCAL BRANCH-FIRST MANDATE: - All work MUST be done on a dedicated local branch (<github-username>/<parent-branch>/<feature>). Never develop directly on main.

IMPORTANT

STRICT SINGLE OPEN PR RULE (CONSOLIDATION MANDATE): - To prevent branch fragmentation, merge conflicts, and stale rebase overhead, there must be at most ONE active open Pull Request at any time. - Check First: Before creating a branch or opening a PR, agents MUST run gh pr list --state open. - Consolidate if an open PR exists: If an open PR already exists targeting main, DO NOT create a new PR or branch. Switch to the active PR's branch (git checkout <branch>), pull latest, apply all new changes and commits to that branch, push, and optionally update the existing PR's title/labels/body (gh pr edit <N>). - New PR Only When Fleet Is Clean: Only create a new branch and open a new PR when gh pr list --state open returns zero open PRs.

IMPORTANT

EXPLICIT USER REQUEST REQUIRED: - AI agents MUST NEVER create Pull Requests automatically or as a default background action. - Agents are only authorized to push branches and open Pull Requests when specifically and explicitly instructed by the user (e.g. *"create a PR to main"*).

CAUTION

TARGET BRANCH IS ALWAYS `main` ONLY (EXCEPT FOR STACKED PRs): - Standard Pull Requests MUST target `main`. - Stacked PR Exception: When deliberately authoring stacked diffs per the stacked-pr-workflow, intermediate dependent PRs target their immediate upstream parent branch (--base <parent-branch>) until that parent branch is merged into main. - Never open Pull Requests against arbitrary dev or staging branches.

2. Pre-PR Validation Checklist

Before opening any Pull Request, the agent/developer MUST ensure:

Local Commits Clean: All intended changes are committed with Conventional Commit messages (git status is clean).

Pre-Commit Gate Passed: The full pre-commit pipeline has executed and passed without errors:

```bash

make pre-commit

```

Branch Pushed to Remote: The local branch is pushed to origin:

```bash

git push -u origin <branch-name>

```

3. Pull Request Creation Runbook

Using GitHub CLI (`gh`)

When requested by the user to create a PR:

Push the local branch to the remote repository:

```bash

git push -u origin <branch-name>

```

Create the PR targeting main with auto-assignment and conventional labels:

```bash

gh pr create \

--base main \

--head <branch-name> \

--title "<type>(<scope>): <concise title>" \

--assignee "@me" \

--label "type/<type>,area/<subsystem>,status/ready-for-review" \

--body "$(cat << 'EOF'

## Pull Request Overview

* <Concise executive summary of changes>

### Subsystem Impact & Boundaries

Subsystem	Impacted?	Description of Changes
Backend API & Handlers	[x]	<details>
Frontend UI / Components	[ ]	N/A
Database & Migrations	[ ]	N/A
CI/CD & DevOps	[ ]	N/A

### Testing & Verification

* [x] make pre-commit executed and passed all validations

* [x] Unit, integration, and AI agent test suites passed (make test)

* [x] Static type checking passed

* [x] Production builds succeeded

### Security & Documentation

* [x] Verified zero credentials/secrets committed

* [x] Relevant agent skills (.agents/skills/) and docs updated

* [x] Release notes added to CHANGELOG.md

EOF

```

4. Post-Creation Confirmation

Once the PR is opened:

Output the generated PR URL (e.g. https://github.com/<owner>/<repo>/pull/123).

Summarize the base branch (main), head branch, assignees, labels, and included commit range.

See .agents/skills/github-pr-issue-automation/SKILL.md for visual formatting guidelines.

pull-request-management