create-pr

name	create-pr
description	Create a pull request with a Conventional Commits title, auto-generated description based on branch changes, and the repository PR template. Use when the user asks to create, open, or submit a pull request.

create-pr

Mission

Create a GitHub pull request for the current branch with a valid Conventional Commits title and an auto-generated description that summarizes the actual changes.

Prerequisites

• git and gh CLI installed and authenticated (gh auth status).
• The gh token must include the project scope for project assignment. If missing, run: gh auth refresh -s project
• The current branch is not main.
• Changes have been committed and pushed to the remote.

PR title rules

The title must pass the repository PR title checker. The authoritative pattern is defined in .github/pr-title-checker-config.json — read that file at runtime to get the current CHECKS.regexp value rather than relying on a hardcoded pattern.

Additional prose rules (not fully enforced by the checker):

• The ! breaking-change indicator must appear after the optional scope and before the :, never between the type and the scope (for example feat!(scope): is invalid; feat(scope)!: is correct).
• The : must be followed by a single space and a non-empty description.

Allowed types: feat, fix, docs, test, ci, chore, refactor.

Format:

<type>[optional scope][!]: <description>

Examples:

• feat(cmdb): add bulk object creation endpoint
• fix(auth): handle expired JWT gracefully
• docs: update README with new env vars
• refactor(services)!: replace requests with httpx

PR description template

The body must use the structure from .github/pull_request_template.md:

# Pull request description

## Describe your changes

<auto-generated summary — see below>

## Issue ticket number and link

<leave blank or fill if the user provides one>

## Checklist before requesting a review

- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] Any dependent changes have been merged and published in downstream modules
- [ ] New or updated tests follow the AAA pattern and `test_<feature>_should_<expected behavior>_when_<state under test>` naming convention

Auto-generating the description

Fill the Describe your changes section by analysing the branch diff against main:

1. Run git log --oneline main..HEAD to list commits on this branch.
2. Run git diff main...HEAD --stat to get a file-level change summary.
3. Run git diff main...HEAD (or read key hunks) to understand the actual changes.
4. Write a concise summary (3-8 bullet points) covering:
   • What changed (new files, modified modules, deleted code).
   • Why it changed (purpose, motivation, context from commit messages).
   • Notable details (new dependencies, config changes, migration steps, breaking changes).

Keep the summary factual and concise. Do not pad with filler.

Workflow

1. Validate branch

   • BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
   • If BRANCH_NAME is main, stop with a warning: cannot create a PR from main.

2. Check for unpushed work

   • Verify there are no uncommitted changes: git status --porcelain.

   • Verify the branch is pushed:

     git fetch origin "$BRANCH_NAME"
     if git rev-parse --verify --quiet "origin/$BRANCH_NAME" > /dev/null; then
       git log "origin/$BRANCH_NAME"..HEAD --oneline
     else
       echo "Branch '$BRANCH_NAME' has not been pushed to origin yet."
       exit 1
     fi
     

   • If there are uncommitted changes or unpushed commits, warn the user and stop.

3. Check for existing PR

   • PR_NUMBER=$(gh pr list --head "$BRANCH_NAME" --state open --json number -q '.[0].number')
   • If a PR already exists, inform the user and provide the PR URL. Stop unless the user wants to update it.

4. Determine PR title

   • Examine the branch commits to infer the primary change type and scope.
   • Propose a Conventional Commits title to the user.
   • Ask the user to confirm or edit the title before proceeding.
   • Validate the final title against the CHECKS.regexp pattern read from .github/pr-title-checker-config.json, and enforce that : is followed by a single space and a non-empty description.

5. Generate PR description

   • Follow the "Auto-generating the description" section above.
   • Build the full body using the PR template structure.
   • Present the generated description to the user for review.

Guardrails

• Never create a PR without user confirmation of the title.
• Never skip the PR template structure.
• Never use --no-verify or force push.
• If gh is unavailable or unauthenticated, ask the user for guidance.
• If the title does not match the required pattern, reject it and ask again. 0