Draft Pull Request

Create a draft pull request, or update the current branch's PR, with a What / Why / How description. The description must let a reviewer understand why the change exists and the shape of the implementation without reading every line of the diff.

Usage

/draft-pull-request [title]

• If a title is provided via $ARGUMENTS, use it as the PR title.
• Otherwise, derive a concise Conventional Commit title from the branch name and commit history.

Bundled References

Process

1. Preflight: find or prepare the PR

BASE_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name')
git branch --show-current
git status --short --branch

# Reuse an existing PR for this branch instead of opening a duplicate
gh pr view --json number,url,title,state,isDraft,baseRefName,body 2>/dev/null

• Open PR exists — set BASE_BRANCH to its baseRefName, which may differ from the default branch, and update its body in step 4. Do not create a second PR or change its draft state.
• On the default branch — create a feature branch named after the change before you continue. Never open a PR from the default branch.
• Uncommitted task changes — commit them first (use commit-atomic when it is available). Leave unrelated or unfamiliar changes uncommitted and mention them in the final report.
• No commits ahead of the base — stop and report that there is nothing to open a PR for.

2. Gather only the context you need

git fetch origin "$BASE_BRANCH" --quiet
git log "origin/$BASE_BRANCH"..HEAD --oneline
git diff "origin/$BASE_BRANCH"...HEAD --stat
git diff "origin/$BASE_BRANCH"...HEAD

• For an existing PR, prefer GitHub's view: gh pr diff <number> and gh pr view <number> --json commits,files. This stays correct when the branch lives in a fork and origin is not the base repository.
• Read the complete diff and enough surrounding code to understand behavior and ownership.
• Read the linked issue, plan, ADR, or handoff when one exists. Collect their links for the body.
• Note the validation you actually ran (tests, lint, typecheck, manual checks) and the results.

3. Write the description

1. Read $SKILL_PATH/references/pr-body-template.md and follow its rules.
2. If the repository has its own PR template (.github/pull_request_template.md, .github/PULL_REQUEST_TEMPLATE/, or docs/pull_request_template.md), keep its headings and checklists, and put the What / Why / How content into the matching sections.
3. When prose alone does not show the shape of the change, read $SKILL_PATH/references/change-outline.md and add one to three small views to How.
4. Write the body to a temporary file, not to the repository:

BODY_FILE=$(mktemp "${TMPDIR:-/tmp}/pr-body.XXXXXX")

4. Publish

# Never force-push.
git push -u origin HEAD

# New PR
gh pr create --draft --base "$BASE_BRANCH" --title "<PR title>" --body-file "$BODY_FILE"

# Existing PR from step 1
gh pr edit <number> --body-file "$BODY_FILE"

Use --body-file instead of --body so that Markdown, backticks, and code fences survive shell quoting.

gh pr edit --body-file replaces the whole body. Before you edit an existing PR, carry over from its current body anything the diff cannot tell you: links, reviewer notes, and checklist items that someone ticked and that still apply.

5. Confirm and report

gh pr view --json url,title,isDraft -q '"\(.url) draft=\(.isDraft) \(.title)"'
rm -f "$BODY_FILE"

Reply with:

- PR: [#<number> <title>](<url>) (<draft or ready for review, from isDraft>)
- Summary: <2-3 sentences: what the PR does and the key decision>
- Validation: <commands run and their results, or "not run">
- Left out: <uncommitted or unrelated changes, or "none">

Guidelines

• Title: Short, imperative, max 72 characters (e.g., feat(auth): add JWT refresh token support).
• Body: Section rules live in references/pr-body-template.md; do not restate them here.
• Language: Write as one person to another — plain, concise, no jargon or filler.

Example

Closes #142

## What

Add a refresh-token endpoint and automatic token renewal in the API client.

## Why

Users are logged out when the 1-hour access token expires, which interrupts long sessions.

## How

- `POST /auth/refresh` validates the HttpOnly refresh cookie and issues a new access token.
- The API client retries a `401` response once, after a refresh, before it shows an error.

```diff
 request(url)
   send with access token
+  if status is 401 and not retried
+    refreshToken()
+    retry once
   return response
```

## Reviewer notes

- Refresh tokens rotate on each use; a reused token revokes the whole session.

## Validation

- `bun test src/auth` — 24 passed
- Manual: session stays signed in after the access token expires