create-pr

Role: Senior engineer opening a pull request or merge request. Goal: Auto-generate a complete, reviewer-ready PR/MR 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/MR immediately.

Step 1 — Parse arguments

Parse $ARGUMENTS for:

• --base <branch> — target branch for the PR/MR (skip inference if provided)
• --ticket-id <id> — ClickUp or issue ID to reference (optional)
• --provider <auto|github|gitlab> — host provider to use; default is auto
• --auto — skip all confirmation steps and create the PR/MR without asking

Capture any provided values. Set AUTO_MODE = true if --auto is present. Set PROVIDER_INPUT = auto when --provider is omitted. Reject any provider value outside auto, github, or gitlab with a clear error before doing network operations.

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 detect provider and extract host/owner/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 HOST, OWNER, and REPO from the remote URL:

• GitHub SSH: git@github.com:owner/repo.git
• GitHub HTTPS: https://github.com/owner/repo.git
• GitLab SSH: git@gitlab.com:owner/repo.git or git@gitlab.example.com:group/subgroup/repo.git
• GitLab HTTPS: https://gitlab.com/owner/repo.git or https://gitlab.example.com/group/subgroup/repo.git

Determine PROVIDER:

• If --provider github was passed, use github.
• If --provider gitlab was passed, use gitlab.
• If --provider auto is active and origin contains github.com, use github.
• If --provider auto is active and origin contains gitlab.com, use gitlab.
• If --provider auto is active and the host is not GitHub, treat remotes whose host or path contains gitlab as self-hosted GitLab and use gitlab.
• If auto-detection cannot identify the provider, stop and ask the caller to rerun with --provider github or --provider gitlab.

For GitLab repositories with nested groups, keep the full namespace as OWNER (for example, group/subgroup) and the final path segment as REPO.

If the working tree has uncommitted changes, warn:

"Uncommitted changes detected. These will not be included in the PR/MR. 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/MR title

Derive the PR/MR 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/MR template

The canonical PR/MR body structure is defined in templates/pull_request_template.md at the project root of the ShipFrame 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/MR title type label (inferred in Step 4) or the branch prefix, tick exactly one checkbox:

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 a provider-specific raw/blob URL format for evidence screenshots:

  # GitHub
  https://github.com/<OWNER>/<REPO>/blob/<CURRENT_BRANCH>/.github/evidence/<filename>.png?raw=true
  
  # GitLab
  https://<HOST>/<OWNER>/<REPO>/-/blob/<CURRENT_BRANCH>/.github/evidence/<filename>.png

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

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

Before invoking provider CLIs, write the rendered body to a temporary file and keep its path in BODY_FILE so the user can reuse it if creation fails:

BODY_FILE="$(mktemp -t shipframe-pr-mr-body.XXXXXX.md)"
printf '%s\n' "<rendered PR/MR body>" > "$BODY_FILE"

GitHub provider: gh CLI

Use this path when PROVIDER=github.

First verify the local CLI and authentication:

command -v gh
gh auth status

If gh is missing or unauthenticated, stop and report:

GitHub PR not created. ShipFrame generated the body at <BODY_FILE>.
Install/authenticate GitHub CLI, then rerun:
  brew install gh
  gh auth login
  gh auth status

Create the Draft PR:

gh pr create \
  --title "<PR/MR title>" \
  --body-file "$BODY_FILE" \
  --base "<BASE_BRANCH>" \
  --head "<current branch>" \
  --draft

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

GitHub 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/MR title>",
  body: "<rendered PR/MR body>",
  head: "<current branch>",
  base: "<BASE_BRANCH>",
  draft: true
}

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

GitLab provider: glab CLI

Use this path when PROVIDER=gitlab. There is no GitLab MCP fallback in ShipFrame v1.

First verify the local CLI and authentication:

command -v glab
glab auth status

If glab is missing or unauthenticated, stop and report:

GitLab MR not created. ShipFrame generated the body at <BODY_FILE>.
Install/authenticate GitLab CLI, then rerun:
  brew install glab
  glab auth login
  glab auth status

Create the Draft MR:

glab mr create \
  --title "<PR/MR title>" \
  --description "$(cat "$BODY_FILE")" \
  --target-branch "<BASE_BRANCH>" \
  --source-branch "<current branch>" \
  --draft \
  --yes

If glab mr create fails, report the captured error, include BODY_FILE, and stop. Do not fall back to GitHub MCP for GitLab remotes.

Step 8 — Report

## Pull Request / Merge Request Created (Draft)

Title:    <title>
URL:      <pr_or_mr_url>
Provider: <github|gitlab>
Base:     <BASE_BRANCH> <- <current branch>
Files:    <count> changed
Method:   <gh CLI | GitHub MCP (fallback) | glab CLI>
Body:     <BODY_FILE>

Store PR_URL or MR_URL and the request number/IID in context — downstream skills or agents may need them.