/create-pr

Create a pull request with auto-detected issue closures and proper formatting.

Arguments

• $ARGUMENTS - Optional: PR title override, or "batch" to use batch-fix template

Instructions

1. Verify Branch State

BRANCH=$(git branch --show-current)
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)

# Ensure we're not on main
if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
  echo "ERROR: Cannot create PR from main branch. Create a feature branch first."
  exit 1
fi

# The branch this PR is for. Record it now; step 5 re-asserts it before pushing.
SESSION_BRANCH="${BRANCH}"
PR_HEAD=$(git rev-parse HEAD)

git status
git log main..HEAD --oneline
git diff main --stat

Review the commits and changed files. Understand the full scope of work before drafting the PR.

Assert the branch before you write. Everything below — the diff you summarize, the issues you detect, the branch you push — is derived from HEAD at this moment. HEAD is global to the working copy, so a concurrent session can move it while you are drafting, and a PR body written from one branch's diff pushed onto another is silently wrong. Re-check git branch --show-current against SESSION_BRANCH immediately before any edit to the working tree and again immediately before the push in step 5. Re-check, never remember.

If this skill amends the branch at all (a fixup commit, a rebase, a README touch-up before opening the PR), stage explicit paths: git status --short, then git add the files you changed by name. Never git add -A, git add ., git add -u, git add <dir>/, or git commit -a — a bulk add sweeps another session's file into the PR you are about to open. -u is not the safe one: it restages every tracked file whose worktree copy differs, including files a clean/smudge filter rewrote without you touching them — that is how git add -u turned a tracked 21KB .docx into a git-lfs pointer and committed it as an edit.

2. Detect Closable Issues

Scan for issues this PR should close. Check THREE sources:

# Source 1: Issue numbers referenced in commit messages (#NNN)
git log main..HEAD --format='%s %b' | grep -oE '#[0-9]+' | sort -u

# Source 2: Issue numbers in branch name (e.g., fix/auth-rate-limit-434 → #434)
echo "$BRANCH" | grep -oE '[0-9]+' | while read num; do
  # Verify it's a real open issue
  gh issue view "$num" --json state,title -q 'select(.state == "OPEN") | "#\(.number // empty): \(.title // empty)"' 2>/dev/null
done

# Source 3: Open from-review issues whose title/body matches changed files
CHANGED_FILES=$(git diff main --name-only | head -20)
gh issue list --label "from-review" --state open --json number,title,body --limit 50

For each candidate issue: Verify it's open and the PR's changes actually address it. Don't claim to close an issue the commits don't fix.

Build the CLOSES_LINES list — one Closes #N per confirmed issue:

Closes #434
Closes #447

If branch has commit messages referencing issues (#NNN) but NONE of those issues appear closable, warn the user: "Commits reference #X but the issue is already closed / not found. Proceeding without Closes tags."

3. Draft PR Content

Based on the commits, changed files, and detected issues, draft the PR.

If $ARGUMENTS contains "batch" OR the PR closes 3+ issues, use Batch Fix template. Otherwise use Default template.

Default Template

## Summary

- Change 1
- Change 2
- Change 3

${CLOSES_LINES}

## Test Plan

- [ ] Server tests pass
- [ ] App type-checks clean
- [ ] Manual smoke test

Batch Fix Template

When closing multiple issues in one PR (common for from-review batches):

## Summary

Brief overview of the batch.

| Issue | What changed | Files |
|-------|-------------|-------|
| #434 | Added auth rate limiting | `ws-server.js` |
| #447 | Added deploy rollback tests | `supervisor.test.js` |
| #433 | Auto mode confirmation handshake | `ws-server.js`, `connection.ts`, `SettingsBar.tsx` |

${CLOSES_LINES}

## Test Plan

- [ ] Server tests pass
- [ ] App type-checks clean
- [ ] Dashboard tests pass
- [ ] Manual smoke test

PR Title: Keep under 70 characters. Use conventional commit format: type(scope): summary

For batch-fix PRs: fix: batch from-review fixes (#N, #M, #P) or similar.

Write the exact drafted Markdown body to a task-specific scratch file using the file-writing tool. Also write a task-specific JSON request with repo, branch, head, base, title and body_file (absolute path). Preserve the repository, branch and full head SHA observed in step 1; do not replace them with a later checkout. This durable request carries the verified inputs between tool calls without assuming shell variables survive. Review its title, body and issue closures in step 4.

4. Validate Scope and Authorization

Before creating the PR, verify:

1. Title (proposed)
2. Body (proposed, including Closes tags)
3. Issues to close (list with titles)
4. Branch and base (main)

Creating the PR is part of delegated implementation and an explicit /create-pr request. Proceed within that scope without another routine confirmation. A planning-only request or an explicit user publication hold requires the concrete title/body to be presented before requesting the missing authorization. Never add unrelated work or close an issue whose acceptance this PR does not satisfy.

5. Push and Create PR

Run the following with the actual scratch request path from step 3. It re-asserts the recorded branch and head immediately before pushing, pushes that exact commit, and passes the body file unchanged to GitHub. If either assertion fails, reconcile ownership and redraft from the intended branch before trying again; never silently adopt the new checkout.

python3 - /absolute/path/to/pr-request.json <<'PYTHON'
import json
from pathlib import Path
import subprocess
import sys

request = json.loads(Path(sys.argv[1]).read_text())
required = ("repo", "branch", "head", "base", "title", "body_file")
if any(not isinstance(request.get(key), str) or not request[key].strip() for key in required):
    raise SystemExit("STOP: incomplete PR request")
body = Path(request["body_file"])
if not body.is_absolute() or not body.is_file() or not body.read_text().strip():
    raise SystemExit("STOP: missing or empty PR body file")
branch = subprocess.check_output(["git", "branch", "--show-current"], text=True).strip()
head = subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip()
if branch != request["branch"] or head != request["head"]:
    raise SystemExit("STOP: branch or HEAD changed since the PR draft; reconcile before pushing")
subprocess.run(["git", "push", "-u", "origin",
                request["head"] + ":refs/heads/" + request["branch"]], check=True)
subprocess.run(["gh", "pr", "create", "--repo", request["repo"],
                "--head", request["branch"], "--base", request["base"],
                "--title", request["title"], "--body-file", str(body)], check=True)
PYTHON

6. Verify Issue Links

After PR creation, confirm the Closes tags were recognized:

PR_NUM=$(gh pr view --json number -q .number)

# Verify linked issues appear in PR metadata
gh pr view ${PR_NUM} --json closingIssuesReferences -q '.closingIssuesReferences[].number'

If any expected issues are missing from closingIssuesReferences, the Closes #N syntax may have been malformed. Edit the PR body to fix.

7. Report to User

Output a summary table — this is the PRIMARY output:

| PR | Branch | Closes | Changes |
|----|--------|--------|---------|
| #XX | feat/branch-name | #434, #447, #433 | rate limiting, rollback tests, auto mode confirm |

Then below the table:

• PR URL
• List of issues that will auto-close on merge
• "Ready for review" or next steps

Critical Rules

1. NO attribution — No Co-Authored-By, no "Generated with Claude", no AI mentions. Zero Attribution Policy.
2. Auto-detect issues — Always scan commits, branch name, and from-review issues. Never skip detection.
3. Reuse publication authority — Delegated implementation and an explicit /create-pr request include PR creation; verify scope and proceed without another routine confirmation. Honor explicit publication holds and request only genuinely missing authority with the concrete title/body ready.
4. Closes tags go in the body — Use Closes #N on its own line in the PR body. GitHub only auto-closes from the body, not the title.
5. Verify after creation — Check that closingIssuesReferences matches expected issues.
6. Target main — Always create PRs against main unless the user specifies otherwise.
7. Don't fabricate — Only add Closes #N for issues the PR's changes actually address. If unsure, ask.
8. Assert the branch before you write — record the branch as SESSION_BRANCH in step 1 and re-check git branch --show-current against it before any working-tree edit and again before the push. HEAD is global to the working copy; a concurrent session can move it while you draft.
9. Explicit-path staging — if you stage anything at all, git status --short then git add the changed files by name. Never git add -A, git add ., git add -u, git add <dir>/, or git commit -a. -u is not the safe one: it restages tracked files a clean/smudge filter rewrote behind your back, which is how a tracked 21KB .docx was committed as a git-lfs pointer.