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 onmain.
[!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 openreturns 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
mainONLY:
- All Pull Requests in this repository MUST target
main.- Never open Pull Requests against
dev, feature branches, or temporary staging branches.mainis 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 statusis clean). - Pre-Commit Gate Passed: The full pre-commit pipeline has executed and passed without errors:
make pre-commit - 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:
- Extract authentication token if needed:
export GH_TOKEN=$(grep GITHUB_TOKEN_PERSONAL .env | cut -d'"' -f2) - Push the local branch to the remote repository:
git push -u origin <branch-name> - Create the PR targeting
mainwith 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.mdfor full visual formatting guidelines.