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:

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. Extract authentication token if needed:

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

2. Push the local branch to the remote repository:

   git push -u origin <branch-name>
   

3. 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 |
   | :--- | :---: | :--- |
   | **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 for full visual formatting guidelines.