PR Description Writer

Read the current branch's diff and commit history, then draft a PR description the developer can copy straight into GitHub, GitLab, Bitbucket, or any other platform. After presenting the description, offer to create the pull request directly — supported for GitHub (via gh) and GitLab (via glab).

This is NOT a code review. Don't critique the code, flag lint issues, or suggest refactors. The job is to clearly communicate what changed and why so that reviewers can do their job efficiently.

Workflow

Step 1: Validate Branch

Check the current branch:

git branch --show-current

If the current branch is a main branch (main, master, develop, release), stop and tell the user they need to be on a feature branch. Do not proceed.

Step 2: Gather Context

Run the context-gathering script:

bash scripts/gather_pr_context.sh [base_branch]

If the script isn't available, gather the same info manually:

# Branch name
git branch --show-current

# Commits on this branch
git log main..HEAD --format="- %h %s" --reverse

# Diff stats
git diff main..HEAD --stat

# Full diff (read this — don't just look at stats)
git diff main..HEAD

Replace main with whatever the base branch is.

Step 3: Read the Diff

This is the critical step. Actually read the diff to understand WHAT changed and WHY. Don't just summarize file names or commit messages — understand the intent behind the changes.

For each changed file, understand:

• What was the file's role before and after?
• Is this a new capability, a fix, a refactor, or a config change?
• Does it change any public API surface (endpoints, function signatures, exports)?
• Does it touch the database (schema, migrations, queries)?
• Does it change how the app is built, tested, or deployed?

If the diff is very large (100+ files), focus on:

1. New files first (they reveal the shape of the feature)
2. Files with the most lines changed
3. Migration files, config changes, and API surface changes
4. Skip auto-generated files (lock files, compiled output, snapshots)

Step 4: Determine the Story

Before writing, figure out the narrative:

• What type of change is this? Feature, bug fix, refactor, chore, dependency update, infrastructure change, documentation? This also determines the Conventional Commit prefix for the PR title (see Step 7).
• What's the user-visible or system-visible outcome? If someone asked "what does this PR do?" in one sentence, what would you say?
• What was the approach? Were there alternative approaches? Why this one?
• What's risky? Could anything break? Are there deployment steps? New env vars? Database migrations that need coordination?
• How should a reviewer test this? Manual steps, automated tests added, specific environments to check?

Step 5: Write the Description

Read the template in references/template.md and produce the PR description.

Output it in a fenced Markdown code block (triple backticks) so the developer can copy it directly. The block should contain the raw Markdown they'll paste into their PR form.

Writing rules:

• Derive the description from the actual diff, not just commit messages. Commit messages are often terse or misleading. The diff is the truth.
• Group changes by concern, not by file. "Added input validation for the order form" is better than "Changed OrderForm.tsx, useOrderValidation.ts, orderSchema.ts".
• Be honest about scope. If the PR touches 3 areas, say so. Don't pretend a large PR is simple.
• Flag anything that needs attention: migrations, env vars, breaking changes, deployment order, feature flags.
• If commits follow conventional commit format, use the types (feat, fix, refactor, etc.) to help categorize, but don't just list the commit messages verbatim.
• If a ticket ID was found in the branch name, include it in the description.
• Scale the description to the PR size. A one-line typo fix gets a one-line description. A 500-line feature gets the full template.

Step 6: Offer Refinement and PR Creation

After presenting the description, ask the developer if they want to:

• Adjust the tone or detail level
• Add context you couldn't infer from the code (e.g. the "why" behind a product decision)
• Include specific testing instructions
• Add or remove sections
• Create the pull request (proceed to Step 7 — GitHub and GitLab repos)

Step 7: Create Pull Request (only when the user accepts)

Only proceed with this step when the developer explicitly confirms they want to create the PR. Never auto-create without asking.

Before anything else, detect the hosting platform:

git remote get-url origin

• URL contains github.com → GitHub (use gh)
• URL contains gitlab (any host, including self-hosted) → GitLab (use glab)
• Any other remote → provide the description to copy-paste and stop

1. Determine the base branch for the PR:

   • Use develop if it exists, otherwise fall back to main or master
   • The user can override this

2. Check for uncommitted changes:

   git status
   

   If there are uncommitted changes, ask the user if they want to commit first.

3. Push the branch:

   git push -u origin <branch-name>
   

4. Derive the PR title using Conventional Commit format:

   The title MUST begin with a Conventional Commit prefix. Use the branch name to determine the type:

   Branch prefix	CC type	Notes
   feature/	feat	New functionality
   bugfix/	fix	Bug fix
   hotfix/	fix	Production bug fix
   chore/	chore	Small task or maintenance
   release/	chore	Release preparation

   If the branch name doesn't match any prefix, infer the type from the change type determined in Step 4 (e.g. a bug fix → fix, a new capability → feat).

   Ticket number: Extract a ticket ID from the branch name if present. A ticket ID matches the pattern [A-Za-z]+-[0-9]+ (e.g. ABC-123, proj-42). Always append it at the end of the title in parentheses.

   Format: type: concise description (TICKET-123) — under 70 characters total (excluding the ticket suffix). If no ticket ID is found, omit the parenthetical entirely.

   Examples:

   • feat: add order validation for checkout flow (SHOP-42)
   • fix: resolve null pointer on login (AUTH-7)
   • chore: upgrade dependencies (no ticket found)

5. Create the PR using the appropriate CLI:

   GitHub (gh):

   gh pr create \
     --base <base-branch> \
     --head <branch-name> \
     --title "<Title>" \
     --body "<Description from Step 5>"
   

   GitLab (glab):

   glab mr create \
     --target-branch <base-branch> \
     --source-branch <branch-name> \
     --title "<Title>" \
     --description "<Description from Step 5>"
   

   Pass the body/description using a HEREDOC to preserve formatting.

6. Return the PR URL to the developer.

If the CLI is not available, provide the developer with:

• The description to copy-paste
• GitHub fallback URL: https://github.com/<owner>/<repo>/compare/<base-branch>...<branch-name>
• GitLab fallback URL: https://<gitlab-host>/<owner>/<repo>/-/merge_requests/new?merge_request[source_branch]=<branch-name>&merge_request[target_branch]=<base-branch> (extract host from origin URL)

Edge Cases

Uncommitted changes: If git status shows uncommitted work, let the developer know. The PR description should reflect what's committed, not what's in the working tree.

Empty diff: If there are no commits ahead of the base branch, say so. Don't fabricate a description.

Merge commits: Filter out merge commits when reading the commit log. They add noise without signal.

Squash workflows: If there's only one commit but a large diff, that's fine. The diff is what matters, not the commit count.

Monorepo: If changes span multiple packages/services, organize the "Changes" section by package/service rather than by concern within a single app.

Push failures: If the push fails, check if the remote branch already exists or if there's an authentication issue. Provide helpful error context.

CLI not installed (gh for GitHub, glab for GitLab): Fall back to manual instructions with the generated description and a compare URL.

Important

• Do NOT review or critique the code. That's not this skill's job.
• Do NOT create any files. Output goes in the conversation only.
• Do NOT include sensitive values from the diff (tokens, keys, passwords).
• Do NOT fabricate ticket links or URLs you can't verify.
• Do NOT create a PR without explicit user confirmation.
• Do NOT include bot signatures, attribution lines, or "Generated with..." footers in the PR description or title. The description should read as if a human wrote it.