PR Description Generator

Generate a well-structured PR description for the current feature branch.

When to Use This Skill

Use this skill when:

• Preparing to create a pull request

• Needing a PR description for the current branch

• Integrating with magit-forge for PR creation

Process

Determine the base branch

Run the helper script to find the base branch:

BASE=$(~/.agents/skills/describing-PRs/scripts/find-merge-base.py)

The script outputs a branch name (e.g., origin/main ) that represents the base branch for comparison. It handles cases where you branched from another feature branch, not just main/master.

Options:

• --fetch : Fetch latest remote refs before determining base branch

• --debug : Show how the base branch is determined

Strategy (implemented in the script):

• Try @{upstream} first (the current branch's configured upstream)

• Try origin/HEAD (the remote's default branch)

• Fall back to common defaults: origin/main , origin/master , origin/develop

• If neither works, find the closest remote branch by commit distance

Gather context about the branch

Using the base branch found above:

git branch --show-current git log --oneline <base-branch>..HEAD git diff --no-ext-diff <base-branch>..HEAD --stat git diff --no-ext-diff <base-branch>..HEAD

Analyze the changes

• Identify the purpose of the changes

• Group related commits by theme

• Note any breaking changes or important considerations

Generate the PR description

Write a Markdown file with:

• Title: A concise summary (will be used as PR title)

• Summary: 2-3 sentences explaining the overall purpose

• Changes: Bullet points of key modifications

• Testing: How the changes were tested (if applicable)

• Notes: Any reviewer notes, breaking changes, or follow-up items

Write to the output file

Create the directory and write the description:

mkdir -p .git/magit/posts

Write Markdown content to .git/magit/posts/new-pullreq

Output Format

The generated file should follow this structure:

<PR Title>

Summary

<Brief explanation of what this PR accomplishes and why>

Changes

• <Key change 1>
• <Key change 2>
• ...

Testing

<How changes were tested, or "N/A" if not applicable>

Notes

<Any additional context for reviewers, breaking changes, or follow-up work>

Formatting Guidelines

• Wrap all symbols, variables, function names, file paths, and code references in backticks (e.g., myFunction , CONFIG_VALUE , src/utils.ts )

• Use fenced code blocks for multi-line code snippets

• Keep bullet points concise and scannable

Important Notes

• The file path .git/magit/posts/new-pullreq is used by magit-forge

• Always overwrite the existing file if present

• Keep the description concise but informative

• Focus on the "why" more than the "what" (the diff shows the "what")