aspiers/ai-config / .agents/skills/describing-prs
describing-prs
VerifiedGenerates a pull request description for the current branch and writes it as Markdown to .git/magit/posts/new-pullreq for magit-forge. Use when the user asks for a PR description, PR summary, or write-up of what a branch changes, or is preparing to open a pull request.
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/postsWrite 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-pullreqis 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")
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |