create-pr

name

create-pr

description

Use this skill whenever the user types /create-pr, /pr, or asks to "open a PR", "create a pull request", "make a PR", "submit for review", or similar. If there are uncommitted changes, runs the /commit skill first. Then crafts a well-structured, detailed PR title and body, confirms with the user, and only then opens the PR via gh CLI. Never adds "Co-Authored-by" or any AI attribution. Always follow this skill for any PR creation workflow.

/create-pr — Pull Request Creation Workflow

Overview

Creates a GitHub PR with a high-quality title and description derived from the actual diff and commit history. Always confirms before submitting. Never includes AI attribution.

---

Step 0 — Handle uncommitted changes

Check for uncommitted work first:

git status --short

If there are staged or unstaged changes, run the commit skill before continuing: tell the user "I see uncommitted changes — let me commit those first" and follow the /commit skill workflow. Resume here once clean.

---

Step 1 — Gather context

# Current branch name
git branch --show-current

# Target branch (where the PR will merge into)
git remote show origin | grep "HEAD branch"
# or: gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

# Fetch latest on target
git fetch origin <target-branch>

# Commits in this branch not yet in target
git log origin/<target-branch>...HEAD --oneline

# Full diff stat
git diff origin/<target-branch>...HEAD --stat

# Full diff (for description generation)
git diff origin/<target-branch>...HEAD

Also check for an existing PR on this branch:

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

If one exists, tell the user and ask whether to update it or stop.

---

Step 2 — Check for PR template

ls .github/pull_request_template.md 2>/dev/null \
  || ls .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null \
  || ls docs/pull_request_template.md 2>/dev/null

If a template exists, read it and use it as the structure for the body. Fill in every section; do not leave placeholder text.

---

Step 3 — Craft the PR title

Rules:

• Imperative mood, sentence case ("Add retry logic for Twilio webhooks")
• Concise but descriptive — captures the what, not just the ticket number
• ≤ 72 characters preferred
• If there's a single Conventional Commits-style commit, the title can mirror it
• No "Co-Authored-by", no "Generated by Claude", no AI mentions

---

Step 4 — Craft the PR body

Use this structure (adapt if a repo template exists):

## Summary

What this PR does and why — 2–4 sentences. Business context if relevant.

## Changes

- **Area/module**: what changed and why
- **Area/module**: what changed and why
(bullet points — aim for each one to carry meaningful information, not just file names)

## Testing

How was this verified? Unit tests, manual steps, eval runs, etc.
If not applicable, say so briefly.

## Notes / Follow-ups

Optional: edge cases left for later, known limitations, related issues.

Body quality bar

• Write as a human senior engineer would — clear, confident, no filler
• Each bullet in "Changes" should explain why the change was made, not just what
• Do not include: "Co-Authored-by", "Generated with Claude", or any AI attribution
• Do not include empty sections — omit or merge them if there's nothing to say
• Link issues if branch name or commits reference them (Closes #123)

Example title + body

feat(eval): replace 4-metric evaluator with 14-metric weighted judge

## Summary

The previous evaluation system scored conversations on 4 abstract dimensions,
making it hard to identify specific failure modes. This PR introduces a
14-metric weighted scoring system tunable per scenario via YAML config.

## Changes

- **eval/judge.py**: Implement weighted LLM-as-a-judge with 14 metrics covering
  goal achievement, tool accuracy, latency, and error handling
- **eval/config.py**: Add per-scenario weight overrides loaded from YAML
- **tests/test_judge.py**: Cover each metric with fixture conversations
- **alembic/versions/xxx_add_eval_metrics.py**: Schema migration for new columns

## Testing

- All 14 metrics verified with unit tests against synthetic conversations
- Manual eval run against 505 Junk test suite: scores match expected ranges
- Alembic migration tested on staging Supabase instance

## Notes

Weight defaults were tuned empirically — further calibration after production
data accumulates is tracked in #341.

---

Step 5 — Present and confirm

Show the user the full proposed PR title and body in a code block. Ask:

"Does this PR description look good, or would you like to adjust anything before I open it?"

Wait for explicit approval. Revise if needed. Do not proceed until approved.

---

Step 6 — Open the PR

gh pr create \
  --title "<title>" \
  --body "<body>" \
  --base <target-branch> \
  --head <current-branch>

Add --draft if the user asks for a draft PR.

Report success with the PR URL.

---

Edge Cases

• gh not authenticated: Surface the error, tell the user to run gh auth login.
• Branch not pushed: Push first (git push -u origin <branch>), then create PR.
• PR already exists: Offer to update the description instead (gh pr edit).
• No commits ahead of target: Warn the user — the PR would be empty.