# Draft Pull Request

> Draft pull requests with structured descriptions using gh CLI

- Skill: `jellydn/draft-pull-request` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jellydn/draft-pull-request`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jellydn/draft-pull-request/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: jellydn (https://skillmd.com/u/jellydn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jellydn/draft-pull-request

---


# Draft Pull Request

Create a draft pull request using `gh` CLI with a structured **What / Why / How** description that communicates the purpose and approach of your changes clearly.

## Usage

```bash
/draft-pull-request [title]
```

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

## Process

### 1. Gather context

```bash
# Detect the repository's default branch
BASE_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name')

# Check current branch
git branch --show-current

# Review commit history since branching from base
git log "$BASE_BRANCH"..HEAD --oneline

# Review the full diff
git diff "$BASE_BRANCH"..HEAD --stat
git diff "$BASE_BRANCH"..HEAD
```

### 2. Compose the PR description

Write a structured description following the **What / Why / How** template:

```markdown
## What

[Concise summary of the changes made. What was added, modified, or removed?]

## Why

[The motivation behind this change. What problem does it solve? What opportunity does it capture?]

## How

[Brief explanation of the approach taken. Key technical decisions, patterns used, or trade-offs made.]

## Checklist

- [ ] Tests added or updated
- [ ] Documentation updated
- [ ] No breaking changes (or breaking changes documented above)
```

### 3. Create the draft PR with gh CLI

```bash
gh pr create \
  --draft \
  --title "<PR title>" \
  --body "<structured what/why/how description>"
```

Use `--draft` to signal the PR is not yet ready for review.

### 4. Output the PR URL

After creation, display the PR URL:

```bash
gh pr view --json url -q '.url'
```

## Guidelines

- **Title**: Short, imperative, max 72 characters (e.g., `feat: add user authentication flow`)
- **What**: Describe the surface area of changes — files, components, APIs affected
- **Why**: Explain the business or technical reason — avoid vague phrases like "to improve things"
- **How**: Highlight non-obvious implementation details or trade-offs, not every line changed
- Keep the description concise but complete — reviewers should understand the PR without reading all the code

## Example

```bash
gh pr create \
  --draft \
  --title "feat(auth): add JWT refresh token support" \
  --body "## What

Add a refresh token endpoint and client-side token renewal logic.

## Why

Users were being logged out after the 1-hour access token expiry,
causing friction for long-running sessions. Refresh tokens allow
seamless re-authentication without user interaction.

## How

- Added POST /auth/refresh endpoint that validates refresh tokens
  stored in HttpOnly cookies and issues new access tokens
- Extended AuthService with refreshToken() and revokeToken() methods
- Updated the API client to automatically retry failed requests with
  a refreshed token before surfacing errors to the UI

## Checklist

- [x] Tests added or updated
- [x] Documentation updated
- [ ] No breaking changes (or breaking changes documented above)"
```