Create Pull Request | ai-tools

Stats

Actions

Tags

Create Pull Request | ai-tools

Create Pull Request

Create a pull request for the current branch with automated validation and smart title/description generation.

Usage

/create-pr

Your Task

The user wants to create a pull request targeting master.

Run build doctor - Execute the global ai-tools build-doctor skill:
```
/ai-tools:build-doctor
```
This skill automatically detects the project type, runs the appropriate build/lint/test commands, and fixes any issues it finds.

If build-doctor reports "no frameworks detected": Do NOT silently skip this step. Ask the user whether the project has a build system that should be validated before creating the PR. The project may have build frameworks that detection missed.
Check git status - Verify the current branch and ensure changes are committed:
```
git status
git rev-parse --abbrev-ref HEAD
```
If there are uncommitted changes, warn the user and ask if they want to commit first.
Verify remote is up to date - Check if local branch is ahead of remote:
```
git fetch origin && git status -sb
```
If there are unpushed commits, push them:
```
git push -u origin HEAD
```
Analyze the changes - Gather information about what changed BEFORE creating the PR:

a. Get the list of commits on this branch (compared to master):
```
git log master..HEAD --oneline
```
b. Get the diff summary:
```
git diff master --stat
```
c. Get the full diff for context:
```
git diff master
```
Generate title and description - Based on the analysis, write both as a human developer would:
- Title: Create a concise, descriptive title (max 72 characters) that:
  - Starts with the ticket number if present in the branch name (e.g., MIN-1234)
  - Summarizes the main purpose of the changes
  - Uses imperative mood (e.g., "Add", "Fix", "Update", "Refactor")
  - Sounds like something a developer would actually type — short, specific, lowercase after the verb (e.g., "Fix null ref in order processing", not "Fix Null Reference Exception in Order Processing Pipeline")
- Description: Write a description the way a developer would in a real team:
  - Lead with why the change was made, not a mechanical list of what changed
  - Keep it short — a sentence or two of context, then a few bullets only for non-obvious changes
  - Skip anything the reviewer can see from the diff (renamed files, trivial formatting, etc.)
  - Use plain, casual language — no marketing-speak, no filler phrases like "This PR introduces" or "In order to improve"
  - Don't over-explain. If the change is straightforward, a one-liner description is fine
  - Only mention testing if there's something the reviewer needs to know (e.g., "needs manual QA on Safari" or "added integration tests for the new endpoint")
Create the pull request - Create the PR with the correct title and description from the start:
```
gh pr create --base master --title "<generated-title>" --body "<generated-description>"
```
IMPORTANT: Create the PR with the final title immediately. Do NOT create with a placeholder title and edit later — GitHub workflows trigger on PR creation and will validate the title before any edit can occur.
Report success - Show the user:
- The PR URL
- The generated title
- A summary of what was included in the description
Run workflow doctor - Monitor the GitHub Actions workflow triggered by the PR:

Get the head commit SHA from the PR, then find the workflow run for that commit:
```
gh pr view <PR-NUMBER> --json headRefOid --jq '.headRefOid'
gh run list --commit <head-sha> --limit 1 --json databaseId --jq '.[0].databaseId'
```
Then pass the run ID directly to the workflow doctor:
```
/ai-tools:github-workflow-doctor <run-id>
```

Writing Style

Write the PR title and description the way a busy senior developer would — someone who respects the reviewer's time.

Principles:

No rigid template. Structure should follow naturally from the content. A one-line fix gets a one-line description. A multi-part feature might use a few bullets.
No emoji checkboxes. Don't use ✅ or ❌ in descriptions.
No headers unless they help. A ## Context header for two sentences is noise. Just write the sentences. Use headers only when the PR is large enough that they aid scanning.
No filler. Avoid "This PR...", "These changes...", "In this pull request...", "This commit introduces...". Just state what happened and why.
Be specific. "Fixed the race condition in checkout when two tabs submit simultaneously" beats "Fixed a bug in the checkout flow".
Match the team's voice. Look at recent PR descriptions in the repo and mirror their level of formality and detail.

Avoid these AI tells:

Title Case On Every Word in the title (write naturally: "Fix null ref in order processing")
Overly comprehensive bullet lists that restate the diff
Phrases like "enhance", "streamline", "leverage", "utilize", "robust", "comprehensive", "ensure"
Explaining obvious things ("Updated the import statement to import the new module")
A perfectly symmetrical structure with exactly 3 bullets in every section

Examples

Small fix:

Order total was wrong when discount codes were applied after tax calculation. Moved the discount step before tax.

Medium feature:

Adds webhook retry logic with exponential backoff.

- Failed webhooks retry up to 3 times (1s, 5s, 30s delays)
- Dead-lettered after final failure for manual review
- New `webhook_deliveries` table tracks attempt history

Needed for Acme integration — they have intermittent 502s that resolve within seconds.

Large change:

Migrates auth from session cookies to JWT tokens.

## Why
Session store was the bottleneck under load — 40% of Redis ops were session lookups.
JWTs let us validate stateless and drop that dependency for read-heavy paths.

## What changed
- New `/auth/token` endpoint issues short-lived JWTs (15 min) + refresh tokens (7 days)
- Middleware validates JWT signature instead of hitting Redis
- Session endpoints still work but are deprecated (remove in v3.2)

## Migration
Existing sessions remain valid until natural expiry. No user-facing disruption.

Important Notes

All PRs target master
Build doctor runs first to detect, build, and auto-fix any issues
The branch must be pushed to the remote before creating a PR
If the branch name contains a ticket number (e.g., MIN-1234-feature-name), include it in the PR title
Keep the PR title under 72 characters for better display in GitHub
Use the imperative mood in titles: "Add feature" not "Added feature" or "Adds feature"
NEVER mention Claude, AI, or include AI attribution in commit messages, PR titles, or PR descriptions (no "Co-Authored-By: Claude", no "Generated with Claude", etc.)