Agent Skills/pull-request-management
Autonomous Git & Version ControlSKILL.md

pull-request-management

Runbooks for authoring and managing clean PRs targeting `main` with PR consolidation.

skills-sync CLIGitHubRaw
Install via CLI:skills-sync pull 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) in the **GitHub Backup Automation System** repository.

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**: * All Pull Requests in this repository MUST target **`main`**. * Never open Pull Requests against `dev`, feature branches, or temporary staging branches. `main` is the sole integration branch.

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:

  • Extract authentication token if needed:

    • ```bash

    export GH_TOKEN=$(grep GITHUB_TOKEN_PERSONAL .env | cut -d'"' -f2)

    ```

  • 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 |

    | :--- | :---: | :--- |

    | **Go Backend (Fiber API & WebSockets)** | [x] | <details> |

    | **Python Observatory (FastAPI & Agent)** | [ ] | N/A |

    | **Next.js Frontend (Turbopack)** | [ ] | N/A |

    | **Backup Worker CLI (SQLite)** | [ ] | 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 (Pyright & TypeScript)

    * [x] Production builds succeeded (Go binaries & Next.js Turbopack)

    ### 🛡️ 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/MishraShardendu22/github-backup-automation-system/pull/123`).
  • Summarize the base branch (`main`), head branch, assignees, labels, and included commit range.
  • See [`.agents/skills/github-pr-issue-automation/SKILL.md`](.agents/skills/github-pr-issue-automation/SKILL.md) for full visual formatting guidelines.