pr-description

name

pr-description

description

Generate a pull request description from branch commits and diffs. Use this skill whenever the user asks to write, create, generate, or draft a PR description, pull request summary, PR body, or merge request description. Also trigger when the user says things like "describe this PR", "what should the PR say", "write up these changes", or "summarize this branch for a PR". Even casual phrases like "PR desc" or "write the PR" should trigger this skill.

PR Description Generator

Generate a structured pull request description by analyzing all commits on the current branch compared to the base branch.

Gathering context

1. Determine the base branch. If the user provides one as an argument, use that. Otherwise default to main.
2. Get the merge base: git merge-base <base-branch> HEAD
3. Get all commits since the merge base with full messages: git log --reverse --format="### %s%n%n%b" <merge-base>..HEAD
4. Get the full diff: git diff <merge-base>..HEAD
5. Get the list of changed files grouped by status: git diff --stat <merge-base>..HEAD

Read through the commits and diff carefully. Understand not just what changed but why—commit messages often explain motivation, and the diff reveals the actual behavioral changes.

Writing the description

The description has three sections: a summary paragraph, a categorized summary, and a features breakdown.

The summary paragraph

Write 1-3 natural paragraphs at the top (no heading) that explain the overall motivation and purpose of the changes. This is the most important part—it should tell someone why this PR exists, not just catalog what it touches.

Lead with specific, concrete names—action names, parameter names, the actual things that changed. Don't abstract them into vague categories like "new looping capabilities" when you can say "Adds do_while_item action." The reader should know exactly what's in this PR from the first sentence.

Think about it from the perspective of a reviewer or someone reading the changelog: what problem was being solved? What was broken or missing before? If there are breaking changes, call them out here so they're impossible to miss.

Don't start with "This PR..."—just lead with the substance. For example: "Adds do_while_item action and fixes several issues with Docker sandbox environments..." or "The caching layer was silently dropping entries when..."

The categorized summary

## Summary

### Enhancements
 - Description of each enhancement, being specific about parameter names and behaviors added.

### Bug Fixes
 - **Breaking: description here** (for fixes that change existing behavior)
 - Description of each fix

Guidelines:

• Only include ### Enhancements or ### Bug Fixes if there are items for that category. Skip empty categories entirely.
• Do not include Documentation or Refactoring sections. Only include Enhancements and Bug Fixes. If a refactor changes observable behavior, list it as an enhancement.
• Each bullet should be concise but specific—mention parameter names, function names, and concrete behavioral changes rather than vague descriptions.
• For new actions or parameters with non-obvious behavior, explain the semantics. For example: "Unlike while_item, the condition is evaluated after the actions, so iteration is 1 on the first condition check."
• For bug fixes, describe outcomes rather than implementation details. Say "Both the full and log displays can now be cleanly exited" rather than "by raising KeyboardInterrupt from the signal handler."
• Explain why something matters, not just what it does. Say "making it easier to see which parameters were actually used" rather than "for easier debugging."
• Bold any breaking changes with the **Breaking:** prefix. A change is breaking if it alters existing behavior that consumers may depend on.

The features breakdown

This section covers the project's core components: Fixtures, Metrics, Policies, Sandbox, Scorers, Solvers, Tools, and Utils. Other changes like CLI, configuration, infrastructure, or internal refactoring belong in the Summary section bullets, not here.

## Features

### New

#### Scorers

`ScorerClassName`
: Description of the feature.

#### Tools

`tool_function_name`
: Description of the feature.

### Updated

#### Solvers

`SolverClassName`
: Description of changes, including new or removed props.

### Removed

#### Fixtures

`FixtureClassName`
: Why the feature was removed.

Guidelines:

• Only include components from the core feature categories: Fixtures, Metrics, Policies, Sandbox, Scorers, Solvers, Tools, and Utils. Do not include CLI changes, configuration, infrastructure, or other non-feature code.
• Group features under the appropriate #### sub-heading matching the category they belong to (e.g., #### Scorers for classes in scorers/).
• Use the definition list format: parenthesized backtick-wrapped name on its own line, then : followed by the description on the next line.
• Only include ### New, ### Updated, or ### Removed sections that have content. Skip empty ones.
• Skip the entire ## Features section if no features were changed.

The dependencies breakdown

Place this section between Summary and Features. Check the diff for changes to dependency files (e.g., pyproject.toml, uv.lock, package.json, requirements.txt, Cargo.toml, go.mod, etc.) and list any dependency changes.

## Dependencies

### New
- `dependency-name` v0.0.0

### Upgraded
- `dependency-name` v0.0.0 -> v1.0.0

### Removed
- `dependency-name`

Guidelines:

• Only include ### New, ### Upgraded, or ### Removed subsections that have content.
• Skip the entire ## Dependencies section if there are no dependency changes.
• Include the version for New and Upgraded dependencies. For Upgraded, show the old and new version with ->.
• For Removed dependencies, just the name is sufficient.

Output

Output the full PR description as markdown. Do not wrap it in a code fence—just output the raw markdown text so the user can copy it directly.

Example

Here's an example of a well-written PR description to calibrate tone and structure:

---

Adds RescoringScorer for re-evaluating completed experiment results and introduces a rescore CLI command to drive it. Previously, rescoring required manually re-running experiments with modified configs—now it can be done directly against existing logs.

Also renames --output-dir to --logs-dir across all CLI commands for consistency, and fixes several sandbox reliability issues around Playwright installation timeouts and password-change false positives in honest mode.

Summary

Enhancements

• Added rescore CLI command for re-evaluating experiment results against updated scoring criteria without re-running solvers.
• Breaking: Renamed --output-dir CLI option to --logs-dir across all commands for clarity about what the directory contains.
• Pipeline parameters from scenario YAML files are now validated at startup, catching typos before experiments begin.
• Global pytest plugin loading order is now deterministic, preventing flaky test results when multiple plugins are present.

Bug Fixes

• Fixed Playwright download timeouts in sandbox environments by extending the default timeout.
• Fixed false positives for password-change detection in honest mode by using the fixed salt plugin.
• Fixed process cleanup by using bash instead of Python for killable subprocesses, preventing orphaned processes after experiment cancellation.

Dependencies

Upgraded

• playwright v1.40.0 -> v1.42.0

Features

New

Scorers

RescoringScorer : Re-evaluates completed experiment results against updated scoring criteria. Reads existing solver logs and applies the current scoring configuration without re-running the solver.

Updated

Policies

HonestModePolicy : Updated password-change detection to use the fixed salt plugin, eliminating false positives when the model legitimately changes passwords.

Sandbox

PlaywrightSandbox : Extended default download timeout to prevent Playwright installation failures in slow network environments.

---

Notice how:

• The opening paragraph names RescoringScorer and rescore directly instead of saying "new scoring capabilities"
• Enhancements explain behavioral impact ("catching typos before experiments begin")
• The --output-dir rename is marked as breaking because it changes the CLI interface
• Bug fixes describe outcomes ("preventing orphaned processes") not implementation details
• Features only include core components (Scorers, Policies, Sandbox), not CLI or config changes
• No spaces around em dashes