create-pr

name	create-pr
description	Use when the user wants to create a pull request, raise a PR, or open a PR — extracts JIRA ticket from branch name, drafts a rich PR description, runs gh pr create, and transitions the JIRA ticket status.

Skill: Create PR

Trigger

Invoke this skill when a user asks to:

• Create a pull request, raise a PR, or open a PR
• Address or action code review comments on an existing PR
• Update a PR based on reviewer feedback

Invocation command: /create-pr

---

Process

Step 1 — Gather git context

Run these commands and collect all output before proceeding:

git branch --show-current
git log origin/main..HEAD --oneline
git diff origin/main..HEAD --stat
git diff origin/main..HEAD
git log origin/main..HEAD --format="%B" | head -100

Step 2 — Extract the JIRA ticket

From the branch name, extract the JIRA ticket reference using these rules:

• Branch patterns: dev/AMP-346, dev/AMP346, dev/AMP-346-description, AMP-346
• Normalise to uppercase with hyphen: AMP-346 (not AMP346)
• If no ticket is found in the branch name, scan the most recent commit message for a pattern like AMP-NNN
• If still not found, prompt the user: "I couldn't find a JIRA ticket in the branch name. What's the ticket reference (e.g. AMP-433)?"

Construct the JIRA URL:

https://tools.hmcts.net/jira/browse/<TICKET>

Step 3 — Understand the changes

From the git diff and commit log, determine:

What changed — concrete list of files/components modified:

• Group by type: e.g. build files, test infrastructure, application code, config, docker
• Be specific: "Added subscriptionKey security scheme to components/securitySchemes in the OpenAPI spec" not "Updated OpenAPI spec"

Why it's needed — the business or technical rationale:

• Look for clues in commit messages, branch name, and the nature of the diff
• If the rationale isn't clear from the code, ask the user: "Can you give me a one-line summary of why this change is needed, for the PR description?"

Step 4 — Draft the PR

Title format:

<TICKET> <concise description of the change in plain English>

Example: AMP-346 Instil subscription key in client request to API

Keep the title under 72 characters. Do not include "changes" as the only description — be specific.

Body format:

## JIRA
[<TICKET>](https://tools.hmcts.net/jira/browse/<TICKET>)

## What changed
- <specific change 1>
- <specific change 2>
- <specific change 3>
...

## Why it's needed
<1-3 sentences explaining the motivation — technical debt, bug fix, new requirement, etc.>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Step 5 — Check for uncommitted changes

Before creating the PR, run:

git status
git log origin/main..HEAD --oneline

• If there are uncommitted changes, warn the user: "You have uncommitted changes. Do you want me to commit them first, or create the PR with only the pushed commits?"
• If the branch hasn't been pushed, run git push -u origin <branch> first
• If there are no commits ahead of main, stop and tell the user: "There are no commits ahead of main on this branch. Nothing to PR."

Step 6 — Check for an existing open PR

Before creating a new PR, check if one already exists for the current branch:

gh pr view --json number,url,title,state 2>/dev/null

• If an open PR already exists, switch to Amend PR mode (see below) instead of creating a new one.
• If no PR exists, proceed with creation as normal.

---

Amend PR Mode

Triggered when an open PR already exists for the current branch, or the user asks to address review comments.

Amend Step 1 — Fetch review comments

gh pr view --json number,url
gh api repos/hmcts/api-cp-crime-hearing-results-document-subscription/pulls/<PR_NUMBER>/reviews --jq '.[].body'
gh pr comments --json body,author
gh api repos/hmcts/api-cp-crime-hearing-results-document-subscription/pulls/<PR_NUMBER>/comments --jq '.[] | {path: .path, line: .original_line, comment: .body, author: .user.login}'

List all unresolved review comments grouped by file. Present a summary to the user:

• "I found N review comments. Here's a summary: ..."

The developer is responsible for addressing the comments. Once they have made the fixes, proceed to Amend Step 2.

Amend Step 2 — Confirm fixes are ready

Ask the user: "Have you made the fixes? I'll commit and push them now."

Wait for confirmation before proceeding.

Amend Step 3 — Commit the fixes

Stage and commit only the files changed in response to review feedback:

git add <specific files>
git commit -m "<TICKET>: address PR review comments — <brief summary>"

Do not amend existing commits. Always create a new commit.

Amend Step 4 — Push and update the PR

git push

Then update the PR description to note the review comments have been addressed. Append to the existing body:

## Review changes (<date>)
- <what was changed in response to review>

Use:

gh pr edit --body "$(cat <<'EOF'
<updated body>
EOF
)"

---

Step 7 — Create the PR

Create the PR and capture the returned URL:

PR_URL=$(gh pr create \
  --title "<title>" \
  --body "$(cat <<'EOF'
<body>
EOF
)" \
  --base main)
echo "$PR_URL"

Rules

• Never use "changes" as the sole PR title descriptor. Always describe what the change actually does.
• Always include the JIRA ticket reference in the PR title and body link — if the ticket can't be extracted from the branch name, ask the user before creating the PR.
• No JIRA API calls — do not post PR links to JIRA, do not transition ticket status. The ## JIRA section in the PR body is a plain hyperlink for reviewer convenience only.
• Never force-push or amend existing commits without explicit user instruction.
• Review responses must be new commits — never amend existing commits to address review comments; always commit fresh so the reviewer can see what changed.
• Always confirm before pushing the branch if it hasn't been pushed yet.
• If gh CLI is not authenticated, tell the user to run gh auth login first.

---

Example output

Branch: dev/AMP-346 Extracted ticket: AMP-346

Title:

AMP-346 Add subscription key security scheme and 401/403 responses to OpenAPI spec

Body:

## JIRA
[AMP-346](https://tools.hmcts.net/jira/browse/AMP-346)

## What changed
- Added `subscriptionKey` security scheme (`Ocp-Apim-Subscription-Key` header) to `components/securitySchemes` in the OpenAPI spec
- Updated global security to require both `bearerAuth` and `subscriptionKey`
- Added `401` and `403` responses to all endpoints that were missing them, with descriptive messages
- Added `SubscriptionKeySecurityTest` to verify the spec defines the subscription key scheme, global security requirements, and that all endpoints declare 401/403 responses

## Why it's needed
The API must enforce APIM subscription key authentication alongside JWT bearer auth. The OpenAPI spec was missing the `subscriptionKey` security scheme and was lacking 401/403 response definitions on several endpoints, which left the contract incomplete and untested.

🤖 Generated with [Claude Code](https://claude.com/claude-code)