create-pr

create-pr

Role: Senior engineer opening a pull request.
Goal: Auto-generate a complete, reviewer-ready PR from git context alone. Every section is derived from the diff, commits, branch name, and project files — no manual writing required. When --auto is passed (or when called by another skill/agent), skip all confirmation steps and create the PR immediately.

---

Step 1 — Parse arguments

Parse $ARGUMENTS for:

• --base <branch> — target branch for the PR (skip inference if provided)
• --ticket-id <id> — ClickUp or issue ID to reference (optional)
• --auto — skip all confirmation steps and create the PR without asking

Capture any provided values. Set AUTO_MODE = true if --auto is present.

---

Step 2 — Gather git context

Run all commands via Bash. Capture every output — it feeds every section of the template.

# Current branch
git branch --show-current

# Remote URL (to extract OWNER and REPO)
git remote get-url origin

# Current git user email (to exclude from FYI tagging)
git config user.email

# All remote branches (for base branch inference)
git branch -r --format='%(refname:short)' | sed 's/origin\///'

# Last 20 commits on this branch (used for description and module inference)
git log HEAD --oneline -20

# All changed files vs each candidate base branch (resolved once base is confirmed)
# Run after base is resolved:
git diff <BASE_BRANCH>...HEAD --name-only
git diff <BASE_BRANCH>...HEAD --stat
git diff <BASE_BRANCH>...HEAD

Extract OWNER and REPO from the remote URL:

• SSH: [email protected]:owner/repo.git
• HTTPS: https://github.com/owner/repo.git

If the working tree has uncommitted changes, warn:

"Uncommitted changes detected. These will not be included in the PR. Commit them first or proceed anyway." In AUTO_MODE, proceed without asking.

---

Step 3 — Infer the base branch

If --base was provided, use it as BASE_BRANCH without any confirmation or inference and skip to Step 4. This is always correct when called by implement-task — do not second-guess it.

Otherwise, infer from the remote branches list using this priority order:

1. main
2. master
3. develop
4. staging
5. First release/* branch found
6. If none of the above exist, use the most recently committed remote branch

If AUTO_MODE is false and the inferred branch is not main or master, confirm with the user:

"Inferred base branch: <branch>. Is this correct?" In AUTO_MODE, proceed with the inferred branch silently.

If the current branch equals BASE_BRANCH, stop:

"The current branch is the same as the base branch. Switch to a feature branch first."

---

Step 4 — Infer PR title

Derive the PR title from the branch name:

1. Strip the type prefix: feat/, fix/, chore/, refactor/, docs/, hotfix/
2. Strip any ticket/sprint/module prefix (e.g. CU-abc123-, M3-S12-)
3. Replace hyphens and underscores with spaces
4. Title-case the result
5. Prepend the type label in brackets: [Feature], [Fix], [Refactor], [Docs], [Chore], [Hotfix]
6. If a ticket ID is available (from --ticket-id or extracted from the branch name), append it: (CU-abc123)

Example: feat/CU-abc123-user-auth-flow → [Feature] User auth flow (CU-abc123)

---

Step 5 — Populate the PR template

The canonical PR body structure is defined in templates/pull_request_template.md at the project root of the ai-toolbox repo (the repo where this skill lives). Read that file and use it as the exact skeleton — do not invent or remove sections. Populate every placeholder by analyzing the git context from Step 2. Instructions inside each section below describe how to derive the content — follow them precisely. The rendered output must not contain the instruction text or placeholder markers.

---

Section: Description

Using the commit messages and git diff output:

• Write 2–4 bullet points summarising the "Why" (motivation / problem solved) and "What" (what was changed at a high level)
• Every bullet must start with exactly one of these semantic keywords: add, update, fix, refactor, delete
• Do not paste raw commit messages — rewrite them as coherent intent statements
• Be specific: reference function names, component names, or API routes where relevant

---

Section: Type of Change

From the PR title type label (inferred in Step 4) or the branch prefix, tick exactly one checkbox:

Branch prefix / label	Checkbox to tick
feat/ / [Feature]	- [x] Feature
fix/ / [Fix]	- [x] Bug Fix
refactor/ / [Refactor]	- [x] Refactor
docs/ / [Docs]	- [x] Docs
chore/ / [Chore]	- [x] Chore
hotfix/ / [Hotfix]	- [x] Hotfix

Leave all others unchecked.

---

Section: Related Ticket

• If --ticket-id was provided, format it as a ClickUp URL: https://app.clickup.com/t/<id>
• If a ticket ID was extracted from the branch name (e.g. CU-abc123), use the same format
• If no ticket is available, write: N/A

---

Section: Module

Parse the branch name and the last 20 commit messages for:

• Migration Number / Section Name — look for patterns like M1, M2, M3, migration-1, section-2 in the branch name or commits. Extract as M{N}. If not found, write <!-- TBD -->.
• Sprint — look for patterns like S12, sprint-12, sprint/12 in the branch name or commits. Extract as S{N}. If not found, write <!-- TBD -->.

Never invent values. Placeholders are correct when data is absent.

---

Section: Shared Code Impact

Inspect the list of changed files (git diff --name-only) for any files inside directories that suggest shared or cross-cutting code:

• Common directory names: shared/, core/, common/, lib/, utils/, helpers/, hooks/, composables/, services/, types/, constants/

If any matches are found:

• Answer: Yes
• List each affected file path
• Add: Team notified: No (the author must verify before merge)

If no matches: Do not include the ### Shared Code Impact section in the rendered PR body.

---

Section: Breaking Changes

Analyze the git diff and commit messages for indications of breaking changes, such as:

• Modified or removed API route parameters/responses
• Changes to shared library function signatures/interfaces
• Database schema changes that remove or alter columns
• Commit messages containing BREAKING CHANGE: or ! in the type prefix (e.g. feat!:)

If breaking changes are detected:

• Answer: Yes
• Describe what breaks and the required migration path for other developers

If no breaking changes: Do not include the ### Breaking Changes section in the rendered PR body.

---

Section: FYI

1. Check if a CODEOWNERS file exists at the project root or .github/CODEOWNERS.
   If it exists, read it and extract GitHub handles (@username) mapped to the changed files.

2. Also run:

   git log <BASE_BRANCH>...HEAD --invert-grep -E --format="%ae" -- <changed files> | sort | uniq
   

   Map contributor emails to GitHub handles where possible (use the handle from CODEOWNERS if the same person appears there).

3. Combine both sources into a de-duplicated list of @handles.

4. Mandatory: remove the current PR author's handle from the list (identified by git config user.email from Step 2).

5. If the list is empty after deduplication, write: No additional stakeholders identified.

---

Section: Screenshots

Inspect the changed file paths for UI indicators:

• Directories: pages/, views/, routes/, screens/, app/, src/app/
• File extensions or names containing: .vue, .svelte, Page., View., Screen., Layout.
• Any component file touched inside a route-level directory

If UI changes are detected:

• List each modified route or page
• For each, provide the GitHub raw URL format for evidence screenshots:

  https://github.com/<OWNER>/<REPO>/blob/<CURRENT_BRANCH>/.github/evidence/<filename>.png?raw=true
  

• Note: "Add screenshots at the paths above before requesting review."

If no UI changes: write: No UI changes in this PR.

---

Section: Test Plan

Derive a concrete, ordered checkbox list a reviewer can follow to verify the changes end-to-end.

Rules:

• Every step must come from the actual diff — no generic steps like "verify the app works"
• Start from the entry point a real user or caller would use (navigate to a route, call an endpoint, trigger an action)
• Cover the happy path first, then at least one edge or error case if changes touch validation, error handling, or conditional logic
• Include any required setup (env vars, feature flags, seed data, running migrations)
• One action per checkbox — short and imperative
• If the change is backend-only: describe the API call (method, endpoint, payload, expected response)
• If the change is UI-only: describe the user interaction and the expected visual or functional outcome
• If new tests were added: include a step to run them with the specific command (e.g. npm test -- --testPathPattern=<file>)

Format:

- [ ] <imperative step>
- [ ] <imperative step>

---

Section: Release Readiness

• Ready for release: Yes — if all test plan steps are expected to pass based on the implementation
• Needs additional work: No — unless there are known gaps, open questions, or incomplete items identified during implementation

---

Step 6 — Render and confirm

Assemble the full PR body using this exact structure:

## Description 📝
<populated description bullets>

### Type of Change
<checkbox list with exactly one item checked based on branch type>

### Related Ticket
<ticket URL or "N/A">

### Module
- Migration: <M{N} or TBD>
- Sprint: <S{N} or TBD>

### Shared Code Impact
<Include only if Yes: file list and Team notified>

### Breaking Changes
<Include only if Yes: describe what breaks and the migration path>

### FYI 🙋
<@handles or "No additional stakeholders identified.">

### Screenshots 📸
<screenshot entries or "No UI changes in this PR.">

### Test Plan 🧪
<checkbox list>

### Release Readiness
- Ready for release: <Yes/No>
- Needs additional work: <Yes/No>

If AUTO_MODE is false, present the rendered body and the inferred title to the user and ask:

"Does this PR look correct? Reply Yes to create it, or paste corrections." Apply any corrections before proceeding.

If AUTO_MODE is true, skip confirmation and proceed immediately.

---

Step 7 — Create the PR

All PRs must be created as Draft. This is non-negotiable — never omit --draft.

Primary: gh CLI

gh pr create \
  --title "<PR title>" \
  --body "<rendered PR body>" \
  --base "<BASE_BRANCH>" \
  --head "<current branch>" \
  --draft

If the command exits with a non-zero status, capture the error and proceed to the fallback below.

Fallback: GitHub MCP (only if gh CLI fails)

If gh pr create failed, create the PR using the MCP tool:

mcp__github__create_pull_request {
  owner: "<OWNER>",
  repo: "<REPO>",
  title: "<PR title>",
  body: "<rendered PR body>",
  head: "<current branch>",
  base: "<BASE_BRANCH>",
  draft: true
}

If both methods fail, report the errors from both attempts and stop.

---

Step 8 — Report

## Pull Request Created (Draft)

Title:   <title>
URL:     <pr_url>
Base:    <BASE_BRANCH> <- <current branch>
Files:   <count> changed
Method:  <gh CLI | GitHub MCP (fallback)>

Store PR_URL and PR_NUMBER in context — downstream skills or agents may need them.