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:

1. Local Commits Clean: All intended changes are committed with Conventional Commit messages (git status is clean).
2. Pre-Commit Gate Passed: The full pre-commit pipeline has executed and passed without errors:

   make pre-commit
   

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

   git push -u origin <branch-name>
   

3. Pull Request Creation Runbook

Using GitHub CLI (gh)

When requested by the user to create a PR:

1. Push the local branch to the remote repository:

   git push -u origin <branch-name>
   

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

   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.