Skip to content

aspiers/ai-config / .agents/skills/describing-prs

describing-prs

Verified

Generates 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.

FileKindSize
SKILL.mdskill md3.4 KB
scripts/find-merge-base.pyexecutablescript8.7 KB
---
name: describing-prs
description: >-
  Generates 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.
allowed-tools: Bash(~/.agents/skills/describing-prs/scripts/find-merge-base.py:*)
---

# 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

1. **Determine the base branch**

   Run the helper script to find the base branch:

   ```bash
   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

2. **Gather context about the branch**

   Using the base branch found above:

   ```bash
   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
   ```

3. **Analyze the changes**

   - Identify the purpose of the changes
   - Group related commits by theme
   - Note any breaking changes or important considerations

4. **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

5. **Write to the output file**

   Create the directory and write the description:
   ```bash
   mkdir -p .git/magit/posts
   ```

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

## Output Format

The generated file should follow this structure:

```markdown
# <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")
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 implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall